内容
-API 中转服务器
一款通过 SP-API 将 Claude 连接到亚马逊卖家中心的模型上下文协议（MCP）服务器。启用销售数据、库存、财务、报告、费用、赔偿和分析。
>通知（2026 年 月 31 日）：** `axios` npm 包链攻击中短暂地被泄露。恶意版本 `1.14.1` 和 `0.30.4` 在 UTC 时间 3 月 31 日 00:21 至 03:15 之间发布，之后 npm 删除了版本包含一个木马化的依赖项（`plain-crypto-js`），该依赖项安装了一个远程访问木马。**此存储库的 axios 依赖项已固定为.14.0最后一个干净的如果您在攻击窗口期间运行了 `npm install`，请删除 `node_modules` 文件夹并重新安装。参见：[Snyk 咨询](https://snyk.io/blog/axios-npm-package-compromised-supply-chain-attack-delivers-cross-platform/)，[Datadog 分析](https://securitylabs.datadoghq.com/articles/axios-npm-supply-chain-compromise/)。
## 关键功能：无需 AWS 截至 2023 年 10 月，亚马逊 SP-API 不再需要 AWS IAM 凭证。该服务器仅使用WA（使用亚马逊登录）OAuth 2.0**，使设置更简单、更安全。
## 功能
### 核心操作
- **订单**：列出订单、检索订单详情和获取行项目
- **库存**：FBA 库存摘要和详细健康指标（预留 / 无法履行）
- **销售**：按日 / 周 / 月的销售指标以及跨期间汇总
- **目录**：查找单个 ASIN 并搜索目录（2022-04-01 API）
- **商品列表**：产品列表的完全 CRUD 操作 - 创建、读取、更新 / 部分）、删除
财务数据
- **：FBA 丢失 / 损坏库存的赔偿
- **结算**：付款明细和明细
- **费用估算**：每个 FBA 费用估算
- **存储费用**：每月存储费用
- **长期存储费用**：陈旧库存的 LTSF+ 天）
- **财务 API**：财务事件、财务和每个订单的财务事件，用于对账
费用**：IN 或 SKU 和的实时 FBA 费用估算
- **：列出、获取 嵌入阈值为 ）和创建发货发票
### 分析
- **销售和流量**：会话、页面浏览量、转化率、购买框百分比
- **搜索词**：品牌性能（需要品牌注册）
- **市场篮子**：品牌分析市场报告（经常一起购买）
- **重复购买**：品牌分析重复购买行为报告
- **库存台账**：跟踪库存变动和调整和详细视图）
客户反馈**：和浏览节点级评论（需要品牌注册 **定价情报竞争性汇总（价格框、报价数量）和为价格调整者提供的价格
-家 solicitation**： solicitation 操作已交付订单的买评论
### API 领域
-BA 货件 v2024-03-20**：列出 / 创建货件计划和列出 / 获取货件
- **受限数据令牌**：为 PII 访问创建 RDT（例如，买家地址）并在订单详情中使用它们
- **商家履行 v0**：合格的运输服务，创建 / 获取 / 取消商家履行的货件
- **数据亭 2023-11-15**：创建、轮询和列出数据亭查询；下载已完成的查询文档
### 可靠性
- **启动凭证验证** - 服务器在 MCP 传输连接之前交换 LWA 刷新令牌并调用 `/sellers/v1/marketplaceParticipations`。配置错误的 `SELLER_ID`期的刷新令牌家未参与的 `MARKETPLACE_ID` 导致服务器以特定错误拒绝启动，而不是在第一次工具调用时不透明地失败。
- **多市场支持** - 每个市场范围的工具都接受一个可选的 `marketplaceId` 输入。如果省略，则使用配置的 `MARKETPLACE_ID`；如果提供，则在启动时将其与卖家的参与市场进行验证。
- **HTTP 401 时自动刷新令牌** - 如果亚马逊在会话中使缓存的访问令牌失效，客户端会清除缓存、获取新令牌并重试请求一次。
- **显式请求超时 + 重试** - axios 请求在 30 秒后超时，并在 `ECONNABORTED` 时重试。
- **按类别限速**，在可重试的亚马逊错误（429 / 5xx / 网络）时使用指数退避重试
- **结构化的 `SPAPIError`**，包含 `status、`code` 和从亚马逊的 `errors[].details` 捕获的 `details` 字段，用于可操作的错误消息
##条件
- Node.js+
- 亚马逊卖家中心账户
- 在开发者中心注册的 SP-API 应用程序
- LWA 凭证（客户端 ID、客户端密钥、刷新令牌）
## 安装
该项目使用 pnpm。如果启用了 Corepack，则无需设置；否则，请先运行 `npm i -g pnpm`。
```bash
git clone https://github.com/jhrendon/amazon-seller-mcp.git
cd amazon-seller-mcp
pnpm install
pnpm run build
```
## 配置
使用您的凭证创建一个 `.env` 文件：
```bash
cp .env.example .env
```
变量：
```bash亚马逊登录（LWA）OAuth.0 凭证
LWA_CLIENT_ID=1.application-oa2xxxx
LWA=your_lwa
LWA_REFAtzr|your_refresh_token
# 信息
SELLER_ID=your_seller_id
MARK_ID=ATVX0DER
# SP-API 端点（可选，默认为北美）
SP_API_ENDPOINT=https://sellingpartnerapi-na.amazon.com
```
> **`MARKETPLACE_ID` 注意：** 在启动时，服务器调用亚马逊的 `getMarketplace` 并确认您的 `MARKETPLACE_ID`家实际参与的市场之一。使用卖家未注册（例如，`ATVPDKIKX0 适用于仅在的卖家）服务器拒绝启动，并在中列出有效### 市场 ID
地区 | 市场 ||--------|-------------|-----|
| 美国 | Amazon.comKIKX0DER |
| 加拿大 | | A2EUQ1WTGCTBG| 墨西哥 |.mx | A1C64UM0Y8 |
| 英国.co.uk | A1F83G8C2P |
| 德国 | Amazon.de | A6795UKMFR9 |
| 日本 |.jp | A1VC38T7YXB### SP-API 端点
| 地区 | 端点 |
|--------|----------|
| 北美 | https://api-na.amazon.com |
| 欧洲 | httpsapi-eu.amazon.com |
| 远 https://sellingpartner.amazon.com |
##
每次服务器启动时，它都会执行两个真实检查，然后再连接传输：
1.WA 刷新令牌交换**，针对 `api.amazon.com/auth/token`。生成的缓存在 `` 中，以便后续工具调用不再支付刷新成本。
**`GET /1/marketations`**，针对。确认访问令接受，卖家枚举卖家参与如果任一步骤失败，服务器都会以 `process.exit(1)` 将特定错误写入 stderr。例如：
```
Credential:
LWA validation failed: Refresh Token has expired_grant)
```
```
failed:
Configured MARKET "ATVPDKIKX0DER" in this seller's participating
marketplaces: [F83G8ARO7P, A1PA6795UKMFR9, A13V1IB3VIYBER one of those.
```
启动成功后，您会在 `Connected via stdio transport` 横幅之前看到一条确认信息：
```
Validated seller A1B2C3D4E5 participating in 2 marketplace(s): [ATVPDKIKX0DER, A2EUQ1WTGCTBG2]
amazon-seller-mcp v1.0.0 running
Connectedio transport
**重大更改：** 以前使用无效凭证 `.env` 中的占位符值、过令牌或错误MARKETPLACE_ID启动的部署现在将拒绝启动。错误消息准确指出错误，因此修复只需对 `.env` 进行一行## 与 Claude Desktop 一起使用
将您的 Claude Desktop`~/Library/Claude/claude_desktop_config.json` 在 macOS 上）：json
{
"mcpServers": {
"amazon-seller": "command": " "args":path/to/amazon-seller-mcp/build/index.js "env": {
"LWA_CLIENT_IDzn1.application-oa2-client.xxxxx "LWA_CLIENT_SECRET": "your_secret "LWA_REF": "Atzr|",
"SELLER_ID": "your_seller_id",
"MARKETPLACE_ID": "ATVPDKIKX0DER",
"SP_APIhttps://sellingpartnerapi-na.amazon.com }
}
}
}
```
重启 Claude Desktop## 与 Claude Code 一起使用
在中添加 `.mcp.json`：
{
"mcpServers": {
"amazon-seller": {
"command": " "args":build/index.js"],
env": {
"LWA_CLIENT_ID":WA_CLIENT_ID}",
"LWA_CLIENT "${LWA_CLIENT "LWA_TOKEN": "${LWA_REFRESH_TOKEN}",
"SELLER_ID": "${SELLER_ID}",
"_ID": "${MARKETPLACE_ID}",
"SP_API_ENDPOINT": "${SP_API_ENDPOINT}"
}
}
}
```
## 可用工具
范围的工具都接受一个可选的 `marketplaceId` 参数。省略时，使用配置的 `MARKETPLACE_ID`；提供时，将在启动时将其与卖家的参与市场进行验证。
### 订单
| 工具 | 描述 |
|------|-------------|
| `get_orders 按日期范围、状态、履行渠道列出订单 |
| `get_order_details`特定订单的的 `restricted` 启用 字段 |
|_order_items` | 获取订单的行项目（分页### 库存
| 工具 | 描述 |
|------|-------------|
| `get_inventory_summary` | 库存水平和健康状况 |
| `get_inventory_details` | 预 无法数量的详细分解 |
### | 工具 | 描述 |
|------|| `get_sales_metrics` | 按日 / 周 / 月的 |
| `get_sales_summary` | 销售汇总 |
### 目录
| 工具 ||------|-------------|
get_catalog_item`目录中获取IN（202201）|
search_catalog` |、品牌或类别 |
### 商品| 工具 | 描述------|-------------|
get_listing`市场中 SKU商品列表文档（属性、履行可用购买报价、问题）|
| `search` | 按状态 / SKU / productType 列表，返回分页结果 |
| `put_listing` | 创建或完全替换商品列表。**** - 使用 `ings` → ` 首先了解当前状态 |
| `patch_listing` | 应用部分更新 合并补丁 仅更改字段 |
| `delete_listing` | 删除商品列表。**永久且不可** |
###| 工具 | 描述 |
|------|------------- `get_competitive_summary` | 获取一个 ASIN 或最多 20 个 ASIN 的竞争性定价（特色报价、最低价、购买框数量）|
_featured_price_batch` | 或最多 40 个 SKU 的特色（FOEP）|
### Solicitations
| 工具 | 描述 |
|------|-------------|
| `get_solicitation_actions_for_order` | 发现针对订单的哪些买家 solicitation 操作可用 |
| `request_product_review`买家为已交付订单提供产品评论 `Shipped` 状态 |
### 财务报告
| 工具 ||------|-------------|
get_fba_reimbursements` | 损坏库存的赔偿 |
| `get_settlement_report` | |
| `get_fba_fee_estimates 每个 SKU 的 |
| `_fees` | 每月存储费用 |
| `get_longterm_storage_fees` | 陈旧F（365）|
| `get_fba_customer_returns FBA 客户退货数据 |
| `get_fba_inventory_pl | 库存供应天数、推荐补货）|
| `get_all_orders_report` | 按订单日期的平面文件全订单报告 财务 API工具 | 描述------|-------------|
get_financial_events 日期范围内的所有财务事件（销售、费用、赔偿、调整| `get_financial_event_groups`组的财务事件 / 付款明细 |
|_order_financial_events` | 特定订单事件 |
### 发票
| 工具 | 描述 |
|------|------------- `get_invoices 日期范围内列出发货发票，可选按状态筛选 |
| `get` | 下载发货发票 PDF。小于 的 PDF 以 嵌入；较大的仅返回预签名| `create_invoice 生成发货发票。**永久且可能影响** - 验证发货 ID、发票编号行项目后提交 实时费用
工具 | 描述 |
|------|-------------|
| `get_fees_estimate_for_asin` | 实时计算一个 ASIN 或最多 20 个 ASIN 的 FBA估算 |
| `get_fees_estimate_for_sku` | 为单个 SKU 计算 FBA 费用估算，附带 `shippingSpeed` / 加急 / 优先）|
> 基于报告的 `get_fba_fee_estimates`、`get_storage_fees` 和 `get_longterm_storage_fees`（在上面的“费用报告”中）更适合批量。对于重新和交互式查询，请使用实时费用工具。
### 客户反馈
| 工具 | 描述 |
|------|-------------|
| `get_feedback_insights_for_asin` | 一个 ASIN 的评分分布和主题计数（需要品牌注册）|
| `get_feedback_insights_for_browse_node` | 类别的聚合评论洞察 |
### FBA 货件
| 工具 | 描述 |
|------|-------------|
| `list_inbound_plans` | 列出货件计划，分页 |
| `get_inbound_plan` | 获取特定货件计划的详细信息 |
| `create_inbound_plan` | 创建新的货件计划 |
| `list_in_shipments`出货件计划的货件 |
| `get_inbound_shipment` | 获取特定货件的详细信息 |
### 受限数据令牌
| 工具 | 描述 |
|------|-------------|
| `create_restricted_data_token 为 PII 访问创建受限数据令### 商家| 工具 ||------|------------- `get__services` | 列出货件的合格| `create_shipment` | 创建行的货件并 |
| `ipment` | 获取状态、跟踪网址 |
| `cancel_shipment` | 取消商家履行的### 数据亭 工具 ||------|-------------|
create_data_k` | 创建数据（GraphQL| `get_data_query` |和结果文档的 |
| `_kiosk_queries 列出最近的数据亭查询 |
## 示例配置完成后，您可以向 Claude 提出问题
- “上周我的销售额是多少？”
- “显示一月份BA 赔偿金 “我的当前状况如何？”
-我上次付款的结算报告”
- “按 SKU 我的存储费用是多少？”
- “哪些产品的转化率最好？”
- “显示我的长期存储费用报告”
- “查找目录商品 B08N5WRWNW”
- “在 50 美元以下搜索无线耳塞的目录”
- “我的财务事件组，最后 天”
- “显示111-2222222-3 的财务事件”
ASIN B08N5WRWNW 的 FBA 费用是多少？”
- “列出 2025-01-01 后发布的所有 Payable 发票”
- “下载发票 INV-2025- PDF”
- “为货件-123 生成发票，包含两个”
- “ASIN B08N5WRWNW 的评分分布和主题是什么？”
- “在美国 SKU WIDGET-001 的商品- “修补 SKU WIDGET-001 的商品列表：将项目符号更改副本”
- “ASIN B08N5WRWNW 的最低竞争价格是多少？”
- “在 24.99 美元的价格下，SKU WIDGET 能否获得购买框？”
- “请求订单 111-22222223333 的买家提供产品
## 开发
```bash
构建
pnpm run build
# 在运行
pnpm
# 类型检查，不生成pmcheck
# 运行测试
pnpm test
# 运行测试覆盖率报告
pnpm runcoverage
# lint
pnpm run lint
# 格式化
pn format
```
### 测试
`tests/` 目录下，使用 Vit。测试套件现已涵盖 CSV 解析器、凭证验证器、管理器、速率限制器、报告轮询器、SP-API 客户端工厂和所有主要工具组。`vitest.config.ts` 中的 80局覆盖率阈值是一个有抱负的目标 - `pnpm:coverage` 仍将失败工具处理程序和少数实用程序专门的测试，但关键路径已得到充分覆盖。
## 架构
```
src/
├── index.ts # MCP 服务器入口点（验证 → 连接）
├── config/
│ └── index.ts # 配置和 zod 验证
├── auth/
│ ├── token-manager.ts # LWA OAuth 2.0令牌管理（缓存，5分钟缓冲）
│ ├── lwa-validator.ts # 用于启动时间验证的令牌管理器测试缝
│ ├── credential-validator.ts # 启动 LWA + SP-API 市场参与检查
│ └── restricted-token.ts # 受限数据令牌创建
├── client/
│ ├── sp-api-client.ts # Axios 客户端，SPAPIError，重试/退避
│ ├── rate-limiter.ts # 每个端点类别的令牌桶速率限制器
│ └── sellers-api.ts # /marketplaceParticipations 的 SP-API 客户端测试缝
├── tools/
│ ├── index.ts # 工具注册表
│ ├── _shared/ # 共享模式、响应助手、市场解析器
│ │ ├── schemas.ts
│ │ ├── response.ts
│ │ └── marketplace.ts
│ ├── orders.ts # 订单 API 工具
│ ├── inventory.ts # 库存 API 工具
│ ├── sales.ts # 销售 API 工具
│ ├── catalog.ts # 目录 API 工具
│ ├── finances.ts # 财务 API 工具
│ ├── invoices.ts # 发票 API 工具
│ ├── fees.ts # Live 产品费用 API 工具
│ ├── feedback.ts # 客户反馈 API 工具
│ ├── listings.ts # 商品列表 API 工具
│ ├── pricing.ts # 产品定价 API 工具
│ ├── solicitations.ts # 招标 API 工具
│ ├── fba-inbound.ts # FBA 进货 v2024-03-20 工具
│ ├── merchant-fulfillment.ts # Merchant Fulfillment v0 工具
│ ├── data-kiosk.ts # 数据亭 2023-11-15 工具
│ ├── tokens.ts # 受限数据令牌工具
│ └── reports/
│ ├── index.ts
│ ├── _factory.ts # 基于报告的工具的通用工厂
│ ├── additional-reports.ts # 客户退货、库存计划、所有订单等
│ ├── reimbursements.ts # FBA 报销
│ ├── settlements.ts # 结算报告
│ ├── fees.ts # 费用报告
│ └── analytics.ts # 品牌分析
├── types/
│ └── sp-api.ts # TypeScript 定义
└── utils/
├── csv-parser.ts # 报告 CSV 解析
└── report-poller.ts # 异步报告轮询
tests/
├── csv-parser.test.ts # CSV / TSV 解析实用程序
├── credential-validator.test.ts # 启动验证逻辑（模拟依赖）
├── data-kiosk.test.ts # 数据亭查询生命周期
├── fba-inbound.test.ts # FBA 进货计划和发货
├── feedback.test.ts # 客户反馈工具 + Brand Registry 403
├── fees.test.ts # Live 费用工具 + 运速 + 批量限制
├── finances.test.ts # 财务 API 工具
├── inventory.test.ts # FBA 库存摘要和详情
├── invoices.test.ts # 发票工具 + 1 MB PDF 阈值
├── listings.test.ts # 商品列表工具 + patch strip-undefined 逻辑
├── marketplace.test.ts # 市场解析和验证
├── merchant-fulfillment.test.ts # Merchant Fulfillment 工具
├── orders.test.ts # 订单 API 工具 + 分页
├── pricing.test.ts # 定价工具 + ASIN/SKU 批量限制
├── rate-limiter.test.ts # 令牌桶速率限制器
├── report-poller.test.ts # 异步报告轮询和下载
├── reports-factory.test.ts # 通用报告工具工厂
├── restricted-token.test.ts # 受限数据令牌创建
├── sales.test.ts # 销售 API 工具
├── solicitations.test.ts # 招标工具 + 已发货状态守卫
├── sp-api-client.test.ts # Axios 客户端重试和 SPAPIError 详情
├── token-manager.test.ts # LWA 令牌缓存和刷新去重
└── tokens.test.ts # 受限数据令牌工具
```
## 许可证
MIT
## 资源
- [Amazon SP-API 文档](https://developer-docs.amazon.com/sp-api/)
- [SP-API 报告类型](https://developer-docs.amazon.com/sp-api/docs/report-type-values)
- [卖家 API 参考](https://developer-docs.amazon.com/sp-api/docs/sellers-api-v1-reference)
- [MCP 协议](https://modelcontextprotocol.io/)
- [SP-API 不再需要 AWS 凭证](https://developer-docs.amazon.com/sp-api/changelog/sp-api-will-no-longer-require-aws-iam-or-aws-signature-version-4)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器