# Amazon API 规范底座

> Amazon Selling Partner API 与 Amazon Ads API 的权威接口规范服务，通过 MCP 提供。
> 让 agent 在动手之前拿到准确的路径、必填参数、限流值、废弃标记与鉴权头组合，
> 并直接生成可执行的请求描述。**服务端不执行任何 Amazon API 调用，也不接触任何凭证。**

覆盖：138 个 API 规范 ·
1159 个 operation ·
9663 个 schema ·
269 个 Amazon 官方真实请求示例。随 Amazon 变更持续跟进。

## 接入（不需要注册，不需要密钥）

两个 endpoint 相互独立，按需接入。只用 SP-API 就别装 Ads，能省下约 2,100 tokens 的常驻上下文。

| endpoint | 用途 | URL |
|---|---|---|
| sp-api | 订单、库存、商品、报告、Feed、通知 | `https://mcp.sp-api.net/mcp/sp-api` |
| ads-api | SP / SB / SD / DSP / AMC 广告 | `https://mcp.sp-api.net/mcp/ads-api` |

传输是 Streamable HTTP（POST，单次 JSON 响应）。
协议版本 2026-07-28 / 2025-11-25 / 2025-06-18 / 2025-03-26 都支持，会自动协商。

### Claude Code

```bash
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
```

### ChatGPT / Codex CLI

写进 `~/.codex/config.toml`：

```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

在 WorkBuddy 的 MCP Servers 设置里加入（标准 `mcpServers` 结构，HTTP 传输）：

```json
{
  "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`：

```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`：

```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 客户端都能接。POST 到上面的 URL，body 是标准 JSON-RPC：

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

**装完必须重启 agent 会话**——MCP 配置只在启动时加载。

## 额度（1 积分 = 1 次调用）

| | 积分 |
|---|---|
| 匿名（按来源 IP） | 每天 100，不累积 |
| 注册即得 | 2,000，永不过期 |
| 每日自动发放 | 100，可累积至 3,000 |
| 邀请好友 | 双方各 2,000 |

余额分两个钱包：**月度额度**（订阅发放，跨月清零）与**永久积分**（赠送/奖励/购买，不过期）。
扣费先扣月度、后扣永久。每次调用的返回里 `_meta["com.amazonmcp/credits"]` 会带上剩余量。

额度用尽返回的是 `isError: true` 的**工具结果**，不是 HTTP 错误，文案里写明「请勿重试」。

### 在对话里直接绑定账号（推荐）

调 **`link_account`**（不带参数）会返回一个短链接和 6 位码。把链接给用户，
让他用手机打开、微信扫码；扫完之后带上同一个 code 再调一次 `link_account`，
就能取回该账号的密钥，然后你自己把它写进当前客户端的 MCP 配置并提示用户重启会话。
**这个工具不消耗积分**——否则积分用尽的人就永远绑不上账号。

扫码即注册即登录，自动获得 2,000 积分与第一把密钥，
不需要填任何表单。之后可在控制台补绑邮箱与手机号作为找回方式。

### 或者手动拿密钥

在 https://mcp.sp-api.net/register 注册后拿到密钥，配置里加一行即可，endpoint 不变：

```
Authorization: Bearer sk_live_xxx
```

也支持 OAuth 2.1（PKCE + 动态注册），客户端会自己走完，用户只需在浏览器点一次同意。

## 怎么用（重要）

**不要凭记忆回答 Amazon 的路径、参数名或限流值。** 每次动手之前先查。

三步漏斗：

```
1. 定位   spapi_search "orders"          →  拿到候选 ref
          ads_search   "create campaign"
2. 取签名 spapi_op orders-v0:getOrders   →  必填参数、schema、限流、是否 deprecated
          ads_show listSponsoredProductsCampaigns
3. 生成   spapi_request / ads_request    →  可执行的请求描述 + 一条可直接跑的 curl
```

第 3 步返回的 JSON 里凭证是 `${AUTH_TOKEN}` 占位符——**由你本地填充，服务端永远不知道真值**。
拿到之后有两条路执行：直接跑返回的 `curl`，或调 `get_executor` 装一个本地执行器
（几十 KB，零第三方依赖，自动处理 token 刷新、429 退避、翻页、多店铺连接）。

## 工具清单

**sp-api（9 个）**
`spapi_search` 全域检索 · `spapi_op` 单个 operation 完整定义 · `spapi_schema` schema 定义 ·
`spapi_doc` 官方文档正文 · **`spapi_request` 生成可执行请求** · `spapi_list` 按类目浏览
（apis / operations / schemas / docs / ratelimits / reports / feeds / notifications / marketplaces / facets）·
`spapi_changelog` Amazon 变更记录 · `spapi_status` 来源与用量 · `get_executor` 取本地执行器

**ads-api（10 个）**
`ads_search` · `ads_operation` · **`ads_show` 单 operation 完整定义（含官方真实示例）** ·
`ads_schema` · `ads_doc` · `ads_example` 官方真实请求 · **`ads_request` 生成可执行请求** ·
`ads_gap` 有请求但无公开规范的 80 个端点 · `ads_spec` 规范目录 · `get_executor`

全部标了 `readOnlyHint`，客户端可以免确认直接放行。

## 几条容易踩的事实

- `getOrders` 已被 Amazon 标记 **deprecated**，限流只有 **0.0167 次/秒**（约每分钟 1 次）。
  批量拉历史订单要用 Reports API，不要循环调它。
- Ads 有**两套互不兼容的鉴权头**：传统体系 `Amazon-Advertising-API-ClientId` + `Amazon-Advertising-API-Scope`，
  新版 v1 体系 `Amazon-Ads-ClientId` + `Amazon-Ads-AccountId`。混用是 401 最常见的原因。
  另外 `Amazon-Ads-Account-ID`（多一个连字符）和 `Amazon-Ads-AccountId` 是**两个不同的头**。
- Ads 的 `Content-Type` / `Accept` 是带版本的厂商媒体类型（如 `application/vnd.spCampaign.v3+json`），
  写成 `application/json` 会失败。
- 规范里查不到某个端点时，先查 `ads_gap` 再下结论——有 80 个端点确实存在但没有公开规范。
- 涉及 PII 的 SP-API 操作需要 RDT（放在同一个 `x-amz-access-token` 头里），`spapi_request` 会标出来。

## 边界

- 服务端**不执行** Amazon API 调用，**不接收**凭证，**不存储**任何店铺业务数据。
- 单次响应上限 32KB（`get_executor` 除外）。被截断时收窄 limit 或加过滤条件。
- 额度用尽返回的是 `isError: true` 的工具结果而不是 HTTP 错误，文案里会写明「请勿重试」。

人读的文档在 https://mcp.sp-api.net/docs 。