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

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:

Variable	Required	Description
AMAZON_ADS_CLIENT_ID	✅	LwA client id (amzn1.application-oa2-client.…)
AMAZON_ADS_CLIENT_SECRET	✅	LwA client secret
AMAZON_ADS_REFRESH_TOKEN	✅	LwA refresh token (Atzr|…)
AMAZON_ADS_REGION	✅	NA, EU, or FE — must match where the refresh token was issued
AMAZON_ADS_PROFILE_ID		Default advertiser profile (else pass profileId per tool call)
MCP_TRANSPORT		stdio (default) or http
MCP_HTTP_PORT		HTTP port, default 3000
AMAZON_ADS_RATE_LIMIT_RPS		Client-side request ceiling, default 5/s
AMAZON_ADS_CACHE_TTL_SECONDS		Entity-read cache TTL, default 60 (0 disables)
AMAZON_ADS_MAX_RETRIES		Retry attempts for 429/5xx, default 4
LOG_LEVEL		pino level, default info (logs go to stderr)
REPORT_OUTPUT_DIR		Where download_report --saveAs writes files, default ./reports-output

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:

Area	Status
Profiles /v2/profiles	✅ Verified, generally available
Sponsored Products v3 (POST /sp/*/list, versioned media types)	✅ Verified
Sponsored Brands v4 (POST /sb/v4/*/list)	✅ Verified
Sponsored Display (GET /sd/*)	✅ Verified for self-service SD accounts
Reporting v3 (/reporting/reports, GZIP_JSON async)	✅ Verified
Amazon DSP reports & orders	⚠️ Entitlement-gated. Requires a DSP seat with API access; without it Amazon returns 403. Endpoint media-type versions evolve — pin against Amazon's DSP docs for your account type.
AMC workflows/executions	⚠️ Entitlement-gated + evolving. Requires a provisioned AMC instance with your LwA client allow-listed. Endpoint shapes follow the AMC Reporting API; verify against the AMC docs for your instance before relying on them in production.
Write operations (create/update campaigns, bids, budgets)	❌ Intentionally not implemented in v1. This server is read/reporting-only to make it safe against production ad spend. PRs welcome behind an explicit opt-in flag.
Rate limits	Amazon's limits are dynamic and undocumented; this server enforces a client-side ceiling and honors 429 Retry-After, but cannot guarantee you'll never be throttled.

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