文档

快速接入（5 分钟）

一条命令写进你的 agent 配置，重启会话就能用。不需要注册、不需要密钥—— 匿名调用按 IP 给免费额度，够日常试用与轻度开发。要更高额度、要看用量、要管密钥时再注册。

claude mcp add --transport http amazon-spapi https://mcp.sp-api.net/mcp/sp-api

两个 endpoint

SP-API 与 Ads 完全独立，各自一套工具集，可以只装一个。额度共享同一个池。

下面按客户端分节，每节都有一段可以直接复制的配置。找到你在用的那个即可，其余可以跳过。

Claude Code

最省事的一条路：命令行直接加，不用编辑任何 JSON。

claude mcp add --transport http amazon-spapi https://mcp.sp-api.net/mcp/sp-api
claude mcp add --transport http amazon-ads   https://mcp.sp-api.net/mcp/ads-api

需要密钥时的变体

默认不带密钥就能用。当你注册后想把调用记到自己账号下（看用量、拿更高额度）， 再加一个 --header：

claude mcp add --transport http amazon-spapi https://mcp.sp-api.net/mcp/sp-api \
  --header "Authorization: Bearer sk_live_xxx"

验证是否装上：claude mcp list 应该能看到 amazon-spapi，状态 connected。

ChatGPT / Codex CLI

写进 ~/.codex/config.toml。ChatGPT 桌面端的 Codex 与 Codex CLI 共用这份配置。

# ~/.codex/config.toml
[mcp_servers.amazon-spapi]
url = "https://mcp.sp-api.net/mcp/sp-api"

[mcp_servers.amazon-ads]
url = "https://mcp.sp-api.net/mcp/ads-api"

WorkBuddy

在设置里找到 MCP Servers，粘贴下面这段标准 mcpServers 结构即可。

// WorkBuddy 设置 → MCP Servers（标准 mcpServers 结构，HTTP 传输）
{
  "mcpServers": {
    "amazon-spapi": {
      "type": "http",
      "url": "https://mcp.sp-api.net/mcp/sp-api"
    },
    "amazon-ads": {
      "type": "http",
      "url": "https://mcp.sp-api.net/mcp/ads-api"
    }
  }
}

Cursor

写进 ~/.cursor/mcp.json（全局）或项目里的 .cursor/mcp.json。

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "amazon-spapi": { "url": "https://mcp.sp-api.net/mcp/sp-api" },
    "amazon-ads":   { "url": "https://mcp.sp-api.net/mcp/ads-api" }
  }
}

VS Code

写进工作区的 .vscode/mcp.json，Copilot Chat 的 agent 模式会自动加载。

// .vscode/mcp.json
{
  "servers": {
    "amazon-spapi": { "type": "http", "url": "https://mcp.sp-api.net/mcp/sp-api" },
    "amazon-ads":   { "type": "http", "url": "https://mcp.sp-api.net/mcp/ads-api" }
  }
}

其他客户端

任何支持 Streamable HTTP 传输的 MCP 客户端都能直接填 URL。

endpoint : https://mcp.sp-api.net/mcp/sp-api
           https://mcp.sp-api.net/mcp/ads-api
transport: Streamable HTTP（POST，单次 JSON 响应）
protocol : 2026-07-28 / 2025-11-25 / 2025-06-18 / 2025-03-26 均支持
auth     : 可不带；需要更高额度时 Authorization: Bearer <密钥>

协议是普通的 Streamable HTTP：一次 POST，一次 JSON 响应。没有长连接、 没有 SSE 依赖、没有 initialize 握手。详见协议版本一节。

三步用法

规范不是给人翻的，是给模型查的。正确的姿势是漏斗：先定位，再取权威签名， 最后生成请求。370 + 789 个 operation 绝不能一对一暴露成工具——模型选不过来也选不准。

1. search —— 定位spapi_search "orders" 返回精简候选行（operation / schema / doc 一次搜完），几 KB 而已。
2. op / show —— 取权威签名spapi_op orders-v0:getOrders 给出必填参数、schema、限流 0.0167 req/s、是否 deprecated。写任何请求之前必调。
3. request —— 生成可执行请求spapi_request 返回解析好的 URL、query、头、body 骨架、翻页方式、缺失的必填项，外加一条能直接跑的 curl。

第四步在你自己的机器上：把请求描述交给本地执行器，或者直接复制那条 curl。 凭证在这一步才出现，且只出现在你的机器上。

一段真实对话

工具清单

两个 endpoint 各自一套。带 ★ 的是「生成可执行请求」那一步，也是最终要落到的地方。

SP-API（9 个工具）

Ads API（10 个工具）

请求描述格式

spapi_request / ads_request 返回的不是「调用结果」，而是一份怎么调的说明书。 它是纯函数的输出：给定 operation 与参数，永远得到同一份描述。凭证的位置只有占位符。

{
  "method": "GET",
  "host":   { "NA": "sellingpartnerapi-na.amazon.com",
              "EU": "sellingpartnerapi-eu.amazon.com",
              "FE": "sellingpartnerapi-fe.amazon.com" },
  "path":   "/orders/v0/orders",
  "query":  { "MarketplaceIds": "ATVPDKIKX0DER",
              "CreatedAfter":   "2026-08-18T00:00:00Z" },
  "auth":   { "header": "x-amz-access-token", "value": "${AUTH_TOKEN}",
              "rdtRequired": false },
  "rateLimit":  { "rps": 0.0167, "burst": 20,
                  "note": "拉取大量历史订单请改用 createReport" },
  "pagination": { "style": "NextToken", "param": "NextToken" },
  "validation": { "missing": [], "unknown": [] },
  "curl": "curl -sS -X GET \"https://…\" -H \"x-amz-access-token: $LWA_ACCESS_TOKEN\""
}

• host 把三个区域都给出来——我们不知道你在哪个区域经营，由执行器按当前连接选。
• validation.missing 在发请求之前就列出缺了哪个必填项，省一次 400 往返。
• rateLimit.note 是规范原文里的建议，不是模型编的。
• curl 可以直接复制到终端跑，填上自己的 token 即可。

本地执行器

执行器是一个不含任何规范数据的哑执行器：它不知道 Amazon 有哪些 API， 只会执行一份别人给它的请求描述。所有智能都在服务端，所以它只有几十 KB、零第三方依赖。 不装也能用——请求描述里自带的 curl 效果完全一样，只是重试、翻页、token 刷新要你自己来。

curl -sS -X GET \
  "https://sellingpartnerapi-na.amazon.com/orders/v0/orders?MarketplaceIds=ATVPDKIKX0DER" \
  -H "x-amz-access-token: $LWA_ACCESS_TOKEN" \
  -H "user-agent: my-app/1.0 (Language=Python/3.12)" \
  -H "accept: application/json"

get_executor 返回什么

{
  "version": "1.4.2",
  "installPaths": {
    "claude-code": "~/.claude/skills/amazon-exec/",
    "codex":       "~/.agents/skills/amazon-exec/",
    "default":     "~/.agents/skills/amazon-exec/"
  },
  "files": [
    { "path": "SKILL.md",        "content": "---\nname: amazon-exec\n..." },
    { "path": "scripts/auth.py", "content": "#!/usr/bin/env python3\n..." }
  ],
  "sha256": "a3f1…",
  "totalBytes": 48213,
  "postInstall": "安装完成后请重启 agent 会话，Skill 在启动时扫描才会生效。"
}

执行器负责的四件事

• LWA token 刷新：access token 只有 1 小时，自动续；需要 RDT 的受限操作自动换 RDT。
• 429 退避与重试：按 operation 在本地记账，发请求前先做令牌桶预判，主动排队而不是撞到 429 再退。
• 自动翻页：NextToken / cursor 两种模式，--paginate n 控制最多翻几页。
• 多店铺连接：凭证与状态按连接隔离，见多店铺连接。

Agent Skills 是开放标准，但安装目录还没统一：Claude Code 用 ~/.claude/skills/，Codex 及多数其他工具用 ~/.agents/skills/。 Codex 的扫描顺序是：当前目录逐级向上到 repo 根的 .agents/skills， 然后 $HOME/.agents/skills、/etc/codex/skills、内置。

多店铺连接

跨店误操作（改错店的价格、库存、广告预算）是这个产品最危险的失败模式，代价是真金白银。 所以执行器的第一条规则是：没有默认连接。

连接管理命令

exec.py connect    --alias us-main --kind sp-api    # 走 LWA 授权，凭证存 keychain
exec.py list                                       # 列出所有连接
exec.py show       --connection us-main            # 详情（凭证脱敏）
exec.py verify     --connection us-main            # 连通性自检
exec.py disconnect --connection eu-store           # 删除连接与凭证

# 执行一个请求描述
exec.py --connection us-main --paginate 10 '<request-json>'
exec.py --connection us-main --dry-run  '<request-json>'   # 只打印最终请求，不发出

四道防线

1. 无默认连接不指定就拒绝执行，并列出候选。
2. 每次执行回显当前连接[connection: us-main | SP-API NA | seller A1B2C3D4E5 | ATVPDKIKX0DER] —— 模型和人都看得见。
3. 写操作二次确认非 GET 请求默认进入确认流程，打印完整请求与目标连接，要求显式 --yes。可对特定连接预授权 --trust-writes，且控制台可见。
4. marketplace 一致性校验请求里的 marketplaceId 若不在该连接声明的列表中，直接拒绝：A1PA6795UKMFR9 (DE) 不属于连接 us-main (US, CA)。

状态在哪

每个连接的状态严格隔离在自己的子目录下，这是防止跨店串数据的第一道结构性保障。

~/.amazon-mcp/
├── profiles.json          连接元数据（明文，只有别名 / region / profileId / marketplaces）
├── credentials.enc        AES-256-GCM 密文，密钥在 OS keychain
├── state/
│   ├── us-main/           cursor.json · quota.json · seen.db
│   ├── eu-store/
│   └── ads-us/
├── cache/tokens.json      仅 access token（1 小时），加密，可随时丢弃
└── logs/exec.log          脱敏后的执行日志

服务端不需要知道这些：request 是纯函数，区域 / marketplace / profileId 全部由执行器在本地填充。 我们不知道你有几个店、店在哪、卖什么。

认证与密钥

先分清两套完全无关的凭证：服务凭证用来访问我们的 MCP（我们签发）； Amazon 凭证用来访问 Amazon API（Amazon 签发，存在你本地，我们永不接触）。 这一节只讲前者。

用 PAT 直接调

POST https://mcp.sp-api.net/mcp/sp-api
Authorization: Bearer sk_live_xxx
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: spapi_op

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"spapi_op","arguments":{"ref":"orders-v0:getOrders"}}}

• 一台机器 / 一条流水线用一把，出事时可以精确吊销，不影响其他环境。
• 不要提交进代码仓库，也不要贴进对话记录——真实威胁不是「恶意 AI」，而是凭证意外进入模型上下文。
• 定期看「最后使用」与「来源 IP」，长期不用的直接吊销。

额度与限制

计价单位是 MCP 调用次数：一次 tools/call 记 1 次， 无论返回的是 400 字节还是 8KB。两个 endpoint 共享同一个额度池。

超额是渐进的，不会突然断

• 自动去重：60 秒内同一租户、同一工具、同一组参数的重复调用只计 1 次。agent 重试非常常见，重复扣费不合理。
• 字节不是计价单位，只是防批量导出的软锁：单次响应硬上限 32KB，月度字节配额 = 调用配额 × 8KB。正常使用平均约 3KB/次。
• 突发保护独立于月度额度（按档位 30–500 次 / 10 秒），防的是失控 agent 的死循环，触发后数秒自动恢复。

配额用尽是业务状态而非协议错误，所以不返回 HTTP 429（客户端会自动重试）、 也不返回 JSON-RPC error（模型可能读不到内容），而是返回一条模型看得懂的工具结果。 完整档位见定价页。

常见错误排查

下面这些都不是猜的，是规范里查得到的确定答案。遇到问题先对照这张表。

给 AI 读的文档 llms.txt

本页是写给人看的。给 agent 看的那份在 /llms.txt——纯 Markdown、无导航、无营销， 一页说完接入方式、工具清单与调用约定。/llm.md 是同一份内容。

最省事的用法：把地址丢给你的 agent，让它自己去读，比你转述可靠得多。

https://mcp.sp-api.net/llms.txt

直接打开：/llms.txt · /llm.md

协议版本

主线是 MCP 2026-07-28：无状态，没有 initialize 握手，也没有 Mcp-Session-Id。同时兼容 2025-11-25 / 2025-06-18 / 2025-03-26， 客户端按自己支持的版本发即可。

MCP-Protocol-Version / Mcp-Method / Mcp-Name 三个路由头是强制的，且必须与 body 一致，否则返回 400 与 JSON-RPC -32020 HeaderMismatch。网关据此计量与路由，不需要解析 body。 拉 tools/list 时不要带 Mcp-Name。

哪些流量到我们、哪些到 Amazon

延迟参考