文档

快速接入

读 https://mcp.sp-api.net/llms.txt ，按里面的说明帮我接入 Amazon API 规范服务

它会自己判断你在用哪个客户端、把两个 endpoint 都装上、调 link_account 拿密钥，并提示你重启会话。 背后是 llms.txt：一份专门写给模型看的接入说明，里面同时列了 sp-api 与 ads-api 两个 endpoint，以及各家客户端的配置写法。

三条路，任选一条

1. 一句话给 AI（默认） 把上面那句话发给 agent。它会调 link_account 给你一个链接，手机微信扫一下就有账号、 有积分、有密钥，它自己写进配置，你什么都不用复制。
2. 跑安装器 python3 amcp-install.py 不带 --key 时，会直接在终端里画一张二维码， 扫完自动领密钥、写配置、装执行器、自检。安装器在控制台 · 接入页。
3. 手动配置 到登录页扫码开通，再到控制台 · 密钥新建一把， 然后按下面客户端配置里你在用的那个客户端，整段复制。

两个 endpoint

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

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

三步用法

规范不是给人翻的，是给模型查的。370 + 789 个 operation 绝不能一对一暴露成工具——模型选不过来也选不准。 所以默认入口只有一个：一句话问清，不够再展开，最后带参数拿可执行请求。

1. lookup —— 一次问清（默认入口）spapi_lookup "拉上周的订单"，一句话（中文可）或直接给 operationId：一次返回限流、废弃与替代、必填参数、翻页、是否需要 RDT、可跑的 curl，外加 5 个候选，≤3.5KB。Ads 侧 ads_lookup 还会给出该接口要求的鉴权头体系与准确头名、带版本的 Content-Type / Accept。
2. op / schema / doc / example —— 需要细节时再展开要完整 schema、官方文档正文或 Amazon 官方请求示例时，再调 spapi_op（brief=true 取精简签名，refs=[…] 一次最多 12 个）、spapi_schema、spapi_doc / ads_example。
3. lookup + params —— 拿可执行请求带上 params（Ads 再带 profile_id / account_id）再调一次 lookup，或调 spapi_request / ads_request：返回解析好的 URL、query、头、body 骨架、翻页方式、缺失的必填项，外加一条能直接跑的 curl。

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

一段真实对话

工具清单

两个 endpoint 各自一套。带 ★ 的是一步到位的入口：先用它，不够再展开。 get_executor、link_account、get_skill 两边都有，不消耗积分。

SP-API（13 个工具）

Ads API（14 个工具）

请求描述格式

spapi_request / ads_request（以及带 params 的 lookup）返回的不是「调用结果」，而是一份怎么调的说明书。 它是纯函数的输出：给定 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_粘贴你自己的密钥
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"}}}

• 一台机器 / 一条流水线用一把，出事时可以精确吊销，不影响其他环境。每个账号最多 20 把。
• 不要提交进代码仓库，也不要贴进对话记录——真实威胁不是「恶意 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

延迟参考