amazon sp MCP

亚马逊卖家中央MCP服务器

模型上下文协议（MCP）服务器，通过亚马逊销售合作伙伴API（SP-API）为人工智能代理提供对亚马逊卖家中心数据的访问。

概述

此MCP服务器使AI代理能够与亚马逊卖家中心进行交互，使他们能够检索销售数据、库存信息、退货、列表、报告等。专为可扩展性和易用性而构建。

与其他MCP的可组合性

此服务器旨在与其他MCP服务器协同工作，以进行全面的亚马逊业务分析：

• 谷歌表格MCP：存储和检索SKU级别的成本数据（出厂成本、运输成本、利润）
• 数据库MCP：查询历史数据和分析
• 概念/气垫MCP：管理产品路线图和业务工作流程

示例用例：通过将SP-API销售数据与Google Sheets成本数据相结合来计算盈利能力：

1. Amazon MCP检索SKU的销售额
2. Google表格MCP检索成本明细
3. AI代理计算利润率并提供见解

📄 看 GOOGLE_SHEETS_SETUP.md 有关详细的设置说明和电子表格模板。

特性

核心能力

• 销售数据：检索订单数据、销售指标和收入信息
• 返回数据：访问退货请求、退款信息和退货指标
• 库存数据：监控库存水平、FBA/FBM库存和库存健康状况
• 列表数据：获取产品列表、ASIN详细信息和目录信息
• 报告：生成和检索各种卖家报告（销售、库存、退货等）
• 订单管理：获取订单详细信息、发货信息和订单状态

计划的功能

• 订单履行操作
• 定价和竞争分析
• 广告数据集成
• 客户信息
• 性能指标和通知
• 列表创建和更新

建筑

项目结构

amazon_sp_mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── config/
│   │   └── sp-api.ts         # SP-API configuration
│   ├── auth/
│   │   ├── credentials.ts    # LWA (Login with Amazon) authentication
│   │   └── token-manager.ts  # Access token management
│   ├── tools/
│   │   ├── sales.ts          # Sales data tools
│   │   ├── returns.ts        # Returns data tools
│   │   ├── inventory.ts      # Inventory tools
│   │   ├── listings.ts       # Listing tools
│   │   └── reports.ts        # Reports tools
│   ├── utils/
│   │   ├── sp-api-client.ts  # SP-API HTTP client
│   │   └── rate-limiter.ts   # Rate limiting utilities
│   └── types/
│       └── sp-api.d.ts       # TypeScript type definitions
├── tests/
│   ├── unit/                 # Unit tests
│   │   ├── auth/
│   │   │   ├── credentials.test.ts
│   │   │   └── token-manager.test.ts
│   │   ├── tools/
│   │   │   ├── sales.test.ts
│   │   │   ├── returns.test.ts
│   │   │   ├── inventory.test.ts
│   │   │   ├── listings.test.ts
│   │   │   └── reports.test.ts
│   │   └── utils/
│   │       ├── sp-api-client.test.ts
│   │       └── rate-limiter.test.ts
│   ├── integration/          # Integration tests
│   │   ├── sp-api.test.ts
│   │   └── auth-flow.test.ts
│   ├── e2e/                  # End-to-end tests
│   │   └── mcp-tools.test.ts
│   ├── fixtures/             # Test data and fixtures
│   │   ├── orders.json
│   │   ├── returns.json
│   │   └── inventory.json
│   ├── mocks/                # Mock implementations
│   │   ├── sp-api-mock.ts
│   │   └── token-mock.ts
│   └── setup.ts              # Test setup and configuration
├── .env.example              # Environment variables template
├── .env.test                 # Test environment variables
├── jest.config.js            # Jest configuration
├── package.json
├── tsconfig.json
├── tsconfig.test.json        # TypeScript config for tests
├── README.md                 # Main documentation
├── SOP.md                    # Standard Operating Procedure for development
├── TESTING.md                # Testing infrastructure guide
├── ROADMAP.md                # Development roadmap
└── GOOGLE_SHEETS_SETUP.md    # Google Sheets integration guide

技术栈

• 运行时：使用TypeScript的Node.js
• MCP-SDK：@modelcontextprotocol/sdk
• API：亚马逊SP-API（销售合作伙伴API）
• 认证：LWA（使用亚马逊登录）OAuth 2.0
• HTTP客户端：轴或节点获取
• 速率限制：基于SP-API限制的自定义实施
• 测试：玩笑，玩笑，@types/Jest
• 嘲笑：jest-mock，nock（HTTP模拟）
• 代码覆盖率：伊斯坦布尔（经杰斯特）
• CI/CD：GitHub Actions（或您首选的CI平台）

Amazon SP-API集成

认证

服务器使用LWA（使用亚马逊登录）OAuth 2.0进行身份验证：

• 应用程序授权的客户端ID和客户端密码
• 刷新卖家授权令牌
• API请求的访问令牌（自动刷新）

所需凭据

1. AWS凭据：访问密钥ID和秘密访问密钥
2. LWA证书：客户端ID、客户端密码、刷新令牌
3. 卖家/市场信息：卖家ID、市场ID

使用的API端点

• 订单API：订单数据和指标
• 返回API：退货和退款信息
• FBA库存API：FBA库存水平
• 目录项目API：产品列表和ASIN数据
• 报告API：各种卖家报告
• 通知API：实时更新（计划中）

安装说明

先决条件

• Node.js 18+和npm
• 亚马逊卖家中心账户
• 亚马逊SP-API开发者应用程序（已注册）
• 具有SP-API权限的AWS IAM证书

安装

# Clone the repository
git clone 
cd amazon_sp_mcp

# Install dependencies
npm install

# Configure environment variables
cp .env.example .env
# Edit .env with your credentials

# Build the project
npm run build

# Test the server
npm run test

环境配置

创建一个 .env 包含以下变量的文件：

# Amazon SP-API Credentials
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=us-east-1

# LWA (Login with Amazon) Credentials
LWA_CLIENT_ID=amzn1.application-oa2-client.xxxxx
LWA_CLIENT_SECRET=your_client_secret
LWA_REFRESH_TOKEN=Atzr|xxxxx

# Seller Information
SELLER_ID=your_seller_id
MARKETPLACE_ID=ATVPDKIKX0DER  # US marketplace

# SP-API Endpoint
SP_API_ENDPOINT=https://sellingpartnerapi-na.amazon.com

MCP配置

此服务器可与任何兼容MCP的客户端配合使用，包括 克劳德代码 （CLI）和 克劳德桌面版.

克劳德代码（CLI）

添加到您的Claude Code MCP设置文件中（通常 ~/.config/claude/claude_desktop_config.json 或可通过设置访问）：

{
  "mcpServers": {
    "amazon-seller-central": {
      "command": "node",
      "args": ["/path/to/amazon_sp_mcp/build/index.js"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your_access_key",
        "AWS_SECRET_ACCESS_KEY": "your_secret_key",
        "LWA_CLIENT_ID": "your_client_id",
        "LWA_CLIENT_SECRET": "your_client_secret",
        "LWA_REFRESH_TOKEN": "your_refresh_token",
        "SELLER_ID": "your_seller_id",
        "MARKETPLACE_ID": "ATVPDKIKX0DER"
      }
    }
  }
}

适用于克劳德桌面

添加 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或您平台上的同等产品：

{
  "mcpServers": {
    "amazon-seller-central": {
      "command": "node",
      "args": ["/path/to/amazon_sp_mcp/build/index.js"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your_access_key",
        "AWS_SECRET_ACCESS_KEY": "your_secret_key",
        "LWA_CLIENT_ID": "your_client_id",
        "LWA_CLIENT_SECRET": "your_client_secret",
        "LWA_REFRESH_TOKEN": "your_refresh_token",
        "SELLER_ID": "your_seller_id",
        "MARKETPLACE_ID": "ATVPDKIKX0DER"
      }
    }
  }
}

用于完整业务分析的多MCP设置

将此服务器与Google Sheets MCP结合使用，以获得全面的亚马逊商业智能（适用于Claude Code和Claude Desktop）：

{
  "mcpServers": {
    "amazon-seller-central": {
      "command": "node",
      "args": ["/path/to/amazon_sp_mcp/build/index.js"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your_access_key",
        "AWS_SECRET_ACCESS_KEY": "your_secret_key",
        "LWA_CLIENT_ID": "your_client_id",
        "LWA_CLIENT_SECRET": "your_client_secret",
        "LWA_REFRESH_TOKEN": "your_refresh_token",
        "SELLER_ID": "your_seller_id",
        "MARKETPLACE_ID": "ATVPDKIKX0DER"
      }
    },
    "google-sheets": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-gdrive"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_google_client_id",
        "GOOGLE_CLIENT_SECRET": "your_google_client_secret"
      }
    }
  }
}

备注：添加MCP服务器后，重新启动您的Claude Code会话或Claude Desktop应用程序以使更改生效。

验证MCP服务器连接

在克劳德代码中：

# Check available MCP servers
/mcp

# The amazon-seller-central server should appear in the list
# Once connected, you can start using the tools

测试连接 通过询问：

"Can you check if the Amazon Seller Central MCP is connected and list available tools?"

Google表格数据结构示例:

使用SKU成本数据创建电子表格：

AI代理使用示例:

User: "What's the profit margin for SKU ABC-001 last month?"

Agent Actions:
1. Uses Amazon MCP to get sales data for SKU ABC-001
   - Total revenue: $500 (50 units × $10 each)
   - Amazon fees: $75

2. Uses Google Sheets MCP to get cost data for SKU ABC-001
   - COGS: $7.50 per unit
   - Total COGS: $375 (50 units × $7.50)

3. Calculates profit:
   - Profit = $500 - $75 - $375 = $50
   - Margin = 10%

MCP工具

销售工具

• get_orders：检索日期范围内的订单
• get_order_details：获取特定订单的详细信息
• get_sales_metrics：计算销售指标（收入、销售量等）

退货工具

• get_returns：检索退货请求
• get_return_details：获取特定退货的详细信息
• get_refund_info：检索退款信息

库存工具

• get_inventory_summary：获取当前库存水平
• get_fba_inventory：检索FBA库存详细信息
• get_inventory_health：获取库存运行状况指标
• check_stock_levels：检查特定ASIN的库存

列表工具

• get_listings：检索产品列表
• get_product_details：获取特定ASIN的详细信息
• search_catalog：在目录中搜索产品

报表工具

• request_report：请求一份新报告
• get_report：检索已完成的报告
• list_reports：列出可用报告
• get_report_document：下载报告数据

速率限制

亚马逊SP-API有严格的费率限制，因终点而异：

• 订单API：0.0167次请求/秒（每分钟1次请求）
• 报告API：0.0222次请求/秒
• 其他API：各不相同

服务器实现了自动速率限制和请求排队，以符合这些限制。

错误处理

• 401错误时自动刷新令牌
• 瞬态故障的重试逻辑（429，5xx）
• 带有SP-API错误代码的详细错误消息
• 服务不可用时性能下降

发展

在开始开发之前，请阅读 SOP.md -它定义了实现路线图中功能的分步过程。

建筑

npm run build

本地运行

npm run dev

测试

该项目使用Jest进行全面的单元、集成和端到端测试。

# Run all tests
npm run test

# Run tests with coverage
npm run test:coverage

📄 有关详细的测试文档，请参阅 测试.md

开发工作流程

每个功能都应遵循此过程（详见 SOP.md):

1. 研究 -阅读文档并计划实施
2. 实施 -编写干净、键入的代码
3. 测试 -编写全面的测试
4. 验证 -确保测试通过，覆盖率≥80%
5. 清理 -删除死代码并重构
6. 文件 -更新所有相关文件
7. 审查 -自我审查和验证

可扩展性

该服务器设计为易于扩展：

1. 添加新工具：在中创建新的工具文件 src/tools/
2. 添加新API：在中实施新的SP-API端点 src/utils/sp-api-client.ts
3. 自定义数据处理：添加用于数据转换的实用函数
4. 缓存：为频繁访问的数据实现缓存层

安全注意事项

• 永不承诺 .env 文件或凭据
• 使用具有最低权限的IAM角色
• 定期旋转刷新令牌
• 实施审计跟踪的请求日志记录
• 验证所有输入参数

微笑。

确保你的 .gitignore 包括：

# Dependencies
node_modules/

# Environment
.env
.env.local
.env.test

# Build
build/
dist/

# Testing
coverage/
*.lcov
.nyc_output/

# Logs
logs/
*.log

# IDE
.vscode/
.idea/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db

资源

亚马逊SP-API

• 亚马逊SP-API文档
• 卖家中心帮助

MCP协议

• MCP协议规范
• MCP服务器存储库
• MCP SDK文档

补充MCP服务器

要进行完整的亚马逊业务分析，请考虑将这些MCP与此服务器一起使用：

• 谷歌表格MCP: @模型上下文协议/服务器gdrive

- 存储SKU成本数据、利润和业务指标 - 设置： Google Drive MCP设置指南

• PostgreSQL MCP: @模型上下文协议/服务器postgres

- 存储历史数据以进行分析和报告

• 文件系统MCP: @模型上下文协议/服务器文件系统

- 管理产品图像、文档和报告

许可证

麻省理工学院

贡献

欢迎投稿！请遵循以下指南：

📋 阅读 SOP.md 第一 -它包含完整的开发工作流程。

贡献者快速入门

1. 分叉存储库
2. 创建要素分支 (git checkout -b feature/your-feature)
3. 遵循SOP -完成功能的所有7个步骤
4. 确保质量门通过:

- ✅ 所有测试均通过 - ✅ 覆盖率≥80% - ✅ 无TypeScript错误 - ✅ 无跳线错误

1. 更新文档 -README、ROADMAP、内联文档
2. 提交拉取请求

开发标准

• 跟随 SOP.md 所有更改的工作流程
• 在实施之前或同时编写测试（鼓励TDD）
• 保持≥80%的代码覆盖率
• 更新所有面向用户的更改的文档
• 使用常规提交消息(feat:, fix:, docs:等等）

贡献领域

看 ROADMAP.md 对于计划中的功能和 对于开放任务。

支持

关于以下问题：

• SP-API标准：参考亚马逊SP-API文件
• MCP协议：访问modelcontextprotocol.io
• 此服务器：在此存储库中打开一个问题

路线图

该项目正在积极开发中。我们正在采取从MVP到生产就绪的分阶段方法。

电流相位：第一阶段（MVP）-构建核心身份验证和基本工具

📄 有关详细的路线图和功能规划，请参阅 ROADMAP.md