@ppcassist/amazon-ads-mcp

Local MCP proxy for the Amazon Ads API. Sits between Claude Desktop and Amazon's official Advertising MCP server, handling OAuth authentication and access-token refresh automatically.

How it works

1. On startup, exchanges your refresh token for an access token via Amazon OAuth
2. Auto-refreshes the token every 50 minutes (plus an on-the-fly retry if Amazon returns 401)
3. Proxies all MCP requests from Claude Desktop to the Amazon Ads MCP server
4. Injects the required authentication headers on every request
5. Streams SSE responses back to Claude without buffering

Quick start

npx @ppcassist/amazon-ads-mcp setup

The setup command handles the OAuth flow end-to-end, asks whether you want flexible mode (operate across all your marketplaces) or pinned mode (lock to one marketplace), fetches your advertiser accounts, and writes the Claude Desktop config for you.

Restart Claude Desktop after setup completes.

Operating modes

The proxy supports the two account-context modes defined by Amazon's MCP server.

Flexible mode (default)

No scope is pinned in the config. Claude picks the account and marketplace at runtime, per question. Best if you manage multiple marketplaces or multiple accounts.

Config written by setup:

{
  "CLIENT_ID": "amzn1.application-oa2-client...",
  "CLIENT_SECRET": "...",
  "REFRESH_TOKEN": "Atzr|...",
  "REGION": "EU"
}

Pinned mode

One marketplace profile is locked in. Every tool call is scoped to that profile. Simpler mental model if you only manage one marketplace.

Config written by setup:

{
  "CLIENT_ID": "amzn1.application-oa2-client...",
  "CLIENT_SECRET": "...",
  "REFRESH_TOKEN": "Atzr|...",
  "PROFILE_ID": "1234567890",
  "ACCOUNT_ID": "amzn1.ads-account.g.xxxxxxxxx",
  "REGION": "EU"
}

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | CLIENT_ID | yes | Your Amazon LWA application client id | | CLIENT_SECRET | yes | Your Amazon LWA application client secret | | REFRESH_TOKEN | yes | OAuth refresh token for an Amazon Ads user | | REGION | yes | NA, EU, or FE | | PROFILE_ID | optional | Amazon Advertising profile id — sent as Amazon-Advertising-API-Scope | | ACCOUNT_ID | optional | Global advertiser account id — sent as Amazon-Ads-AccountID (needed for the reporting tools) | | MANAGER_ACCOUNT_ID | optional | Sent as Amazon-Ads-Manager-AccountID |

If any of PROFILE_ID / ACCOUNT_ID / MANAGER_ACCOUNT_ID is set, the proxy operates in fixed account context (sending Amazon-Ads-AI-Account-Selection-Mode: FIXED). If none are set, the proxy operates in dynamic account context, and Claude passes account identifiers per tool call.

Note: the Amazon reporting tools require Amazon-Ads-AccountID to be present. In pinned mode, setup writes both PROFILE_ID and ACCOUNT_ID for you so both campaign tools and reporting tools work out of the box.

Manual configuration

If you prefer to edit your Claude Desktop config by hand:

{
  "mcpServers": {
    "amazon-ads": {
      "command": "npx",
      "args": ["-y", "@ppcassist/amazon-ads-mcp"],
      "env": {
        "CLIENT_ID": "amzn1.application-oa2-client.xxxxx",
        "CLIENT_SECRET": "your-client-secret",
        "REFRESH_TOKEN": "Atzr|your-refresh-token",
        "REGION": "EU"
      }
    }
  }
}

Add PROFILE_ID / ACCOUNT_ID / MANAGER_ACCOUNT_ID to env to pin a scope.

Supported regions

| Region | Amazon Ads MCP endpoint | |--------|-------------------------| | NA | https://advertising-ai.amazon.com/mcp | | EU | https://advertising-ai-eu.amazon.com/mcp | | FE | https://advertising-ai-fe.amazon.com/mcp |

Amazon's endpoints are region-scoped — use the one that matches your marketplaces.

How it proxies

All MCP JSON-RPC messages (initialize, tools/list, tools/call, …) are forwarded to Amazon's MCP server with these headers injected:

• Authorization: Bearer <access_token>
• Amazon-Ads-ClientId: <CLIENT_ID>
• Accept: application/json, text/event-stream
• Amazon-Advertising-API-Scope: <PROFILE_ID> (if set)
• Amazon-Ads-AccountID: <ACCOUNT_ID> (if set)
• Amazon-Ads-Manager-AccountID: <MANAGER_ACCOUNT_ID> (if set)
• Amazon-Ads-AI-Account-Selection-Mode: FIXED (if any scope header is set)

Responses (including SSE streams) are forwarded back to Claude as-is.

Troubleshooting

"The provided account identifier header is not supported for this tool" The tool you called requires a different scope header than what you have configured. The most common case is calling a reporting tool with only PROFILE_ID set. Add ACCOUNT_ID to your config, or re-run setup and pick pinned mode (which writes both).

"400 Bad Request — redirect URI not whitelisted" During setup, Amazon rejected the OAuth callback URL. In your LWA Security Profile → Web Settings → Allowed Return URLs, add:

http://localhost:8080/callback
http://localhost:8081/callback
http://localhost:8082/callback

Token refresh failed after the 50-minute timer The proxy will retry once on a 401 before giving up. If it persists, check that your refresh token hasn't been revoked and that your LWA app still has the advertising::campaign_management scope granted.

License

MIT