amazon-ads-mcp

Production-ready MCP server connecting Amazon Advertising data to Claude and any MCP-compatible client.

Query Sponsored Products, Sponsored Brands and Sponsored Display structure and performance, run Amazon DSP reports, and execute Amazon Marketing Cloud (AMC) SQL workflows — all in natural language, with live data straight from the Amazon Ads API. No mock data, ever.

Features

• 23 read-only tools across profiles, Sponsored Products (v3), Sponsored Brands (v4), Sponsored Display, unified Reporting v3, Amazon DSP, and AMC

• Data accuracy by construction — every number comes live from Amazon; downloaded reports pass integrity checks (column presence, non-negative metric invariants, daily date-coverage) and totals are computed server-side so the model never sums truncated samples

• Resilient HTTP layer — OAuth token refresh with single-flight de-duplication, client-side token-bucket rate limiting, exponential backoff with jitter, Retry-After honoring on 429, one automatic re-auth on 401

• Fast on large accounts — TTL response cache for entity reads, nextToken/index pagination passthrough, parallel tool calls are safe (rate limiter serializes the wire)

• Secure by default — secrets only via environment variables, redacted from logs, never written to disk; logs go to stderr (stdout is reserved for the MCP protocol)

• Two transports — stdio for Claude Desktop / Claude Code, streamable HTTP for Docker or remote deployment

• Tested — 36 unit/integration tests including full MCP wire-protocol tests with the Amazon API mocked at the fetch boundary

Related MCP server: Amazon Ads MCP

Architecture

flowchart LR
    subgraph Client["MCP Client"]
        C[Claude Desktop / Claude Code / any MCP host]
    end
    subgraph Server["amazon-ads-mcp"]
        T[MCP tool layer<br/>zod-validated schemas]
        V[Validation & reconciliation]
        H[HTTP client<br/>retries · rate limit · cache]
        A[Token manager<br/>LwA refresh, single-flight]
    end
    subgraph Amazon["Amazon"]
        LWA[Login with Amazon<br/>OAuth token endpoint]
        API[Amazon Ads API<br/>NA / EU / FE]
        S3[Signed report URLs]
    end

    C -- stdio / streamable HTTP --> T
    T --> V --> H
    H --> A --> LWA
    H --> API
    H -- report download<br/>no auth headers --> S3

Async reporting flow (Reporting v3, DSP, AMC all follow it):

sequenceDiagram
    participant Claude
    participant MCP as amazon-ads-mcp
    participant Ads as Amazon Ads API

    Claude->>MCP: create_report(dates, columns, ...)
    MCP->>Ads: POST /reporting/reports
    Ads-->>MCP: reportId (PENDING)
    loop until COMPLETED (1–15 min typical)
        Claude->>MCP: get_report_status(reportId)
        MCP->>Ads: GET /reporting/reports/{id}
    end
    Claude->>MCP: download_report(reportId)
    MCP->>Ads: fetch signed URL, gunzip, validate
    MCP-->>Claude: reconciled totals + row sample (+ optional JSON file)

Prerequisites

You need Amazon Ads API access (this is Amazon's process, not this project's):

1. An Amazon Ads account (seller, vendor, or agency).

2. A Login with Amazon (LwA) security profile with the Amazon Ads API scope approved — apply via the onboarding guide.

3. A refresh token generated through the LwA authorization-code grant for your own account (create authorization grant).

Plus Node.js ≥ 20 (or Docker).

New to all of this? Follow the step-by-step User Guide — it walks through Amazon API onboarding, refresh-token generation, installation, and Claude setup with no prior knowledge assumed.

Installation

git clone https://github.com/Imsamiullah09/amazon-ads-mcp.git
cd amazon-ads-mcp
npm ci
npm run build

Environment variables

Copy .env.example and fill it in:

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config), or copy examples/claude_desktop_config.json:

{
  "mcpServers": {
    "amazon-ads": {
      "command": "node",
      "args": ["/absolute/path/to/amazon-ads-mcp/dist/index.js"],
      "env": {
        "AMAZON_ADS_CLIENT_ID": "amzn1.application-oa2-client.…",
        "AMAZON_ADS_CLIENT_SECRET": "…",
        "AMAZON_ADS_REFRESH_TOKEN": "Atzr|…",
        "AMAZON_ADS_REGION": "NA",
        "AMAZON_ADS_PROFILE_ID": "1234567890"
      }
    }
  }
}

Restart Claude Desktop and ask: “Run a health check on my Amazon Ads connection.”

Claude Code

claude mcp add amazon-ads \
  -e AMAZON_ADS_CLIENT_ID=… -e AMAZON_ADS_CLIENT_SECRET=… \
  -e AMAZON_ADS_REFRESH_TOKEN=… -e AMAZON_ADS_REGION=NA \
  -- node /absolute/path/to/amazon-ads-mcp/dist/index.js

Docker

cp .env.example .env   # fill in credentials
docker compose up -d   # streamable HTTP on http://127.0.0.1:3000/mcp

The compose file binds to localhost only: the HTTP endpoint deliberately ships without its own auth layer (it holds a single advertiser's credentials). For remote access, front it with your own reverse proxy and authentication. For stdio inside Docker: docker run -i --env-file .env -e MCP_TRANSPORT=stdio amazon-ads-mcp.

Example prompts

• “List my advertiser profiles and tell me which marketplaces I'm in.”

• “Show all enabled Sponsored Products campaigns and their daily budgets.”

• “Create a daily campaign performance report for the last 30 days, wait for it, and summarize spend, sales and ACOS by campaign.”

• “Pull a search-term report for May and find queries with clicks but zero purchases.”

• “Which ASINs am I advertising in ad group X?”

• “Run my AMC workflow path_to_conversion for last week and give me the download links.”

More in examples/prompts.md. Full tool reference in docs/API.md.

Data accuracy & reconciliation

• No mock data. Every tool hits the live Amazon Ads API; errors are surfaced (with Amazon's request id) instead of silently degraded.

• download_report validates each report: requested columns present, invariant metrics (impressions, clicks, cost, sales…) non-negative, and daily reports checked for date-coverage gaps.

• Totals are computed once, server-side, and returned alongside a bounded row sample — the model is explicitly instructed to quote reconciled totals rather than re-sum samples.

• Entity reads are cached for 60 s by default (configurable, or disable with AMAZON_ADS_CACHE_TTL_SECONDS=0); report status/downloads are never cached.

• Caveat that applies to any Amazon Ads integration: Amazon's own attribution metrics are restated for up to ~14 days after the fact, so a report pulled today can legitimately differ from the same report pulled next week. That is Amazon-side behavior, not a sync bug.

Verified capabilities vs. assumptions

This project distinguishes what is verified against Amazon's public documentation from what depends on your account's entitlements:

Development

npm run dev        # run from source (tsx)
npm test           # vitest suite (36 tests, no network — fetch is mocked)
npm run typecheck  # strict TS
npm run build      # emit dist/

See docs/ARCHITECTURE.md for module layout and design decisions, and CONTRIBUTING.md for workflow. Security policy: SECURITY.md.

License

MIT