amazonads-mcp

Amazon Ads MCP 服务

一个用于与 Amazon Advertising API 交互的模型上下文协议（MCP）服务。此服务可让 AI 助手访问和管理 Amazon Ads 广告活动、关键词、效果数据等。

功能

此 MCP 服务提供以下工具：

• get_profiles：列出所有可用的 Amazon Ads 配置文件／账户
• get_campaigns：获取广告活动，可按状态和类型进行筛选
• get_campaign_performance：获取广告活动的效果指标（展示次数、点击次数、费用、销售额）
• get_keywords：获取广告活动或广告组的关键词
• update_keyword_bid：更新指定关键词的竞价金额
• create_campaign：创建新的广告活动
• get_product_ads：获取广告活动或广告组的商品广告

前提条件

1. Amazon Ads 账户：你需要一个有效的 Amazon Ads 账户
2. API 凭证：注册以获取 Amazon Ads API 访问权限，并取得以下信息：
   • 客户端 ID
   • 客户端密钥
   • 刷新令牌

获取 Amazon Ads API 凭证

步骤 1：注册应用

1. 前往 Amazon Advertising API
2. 使用你的 Amazon Ads 账户登录
3. 前往开发者中心并创建新应用
4. 你将获得一个客户端 ID和客户端密钥——请保存好！

步骤 2：获取刷新令牌

我们提供了一个辅助脚本，可通过 OAuth 流程获取刷新令牌：

1. 在项目根目录中创建 .env 文件：

   AMAZON_ADS_CLIENT_ID=your_client_id_here
   AMAZON_ADS_CLIENT_SECRET=your_client_secret_here
   

2. 运行 OAuth 辅助脚本：

   npm run get-token
   

3. 浏览器将打开 Amazon 授权页面

4. 登录并授权该应用

5. 脚本将显示你的刷新令牌——将它复制到 .env 文件中

步骤 3：确认所在区域

确定你的广告区域：

• NA：北美（amazon.com）
• EU：欧洲（amazon.co.uk、amazon.de 等）
• FE：远东（amazon.co.jp 等）

安装

1. 克隆此代码仓库：

git clone <your-repo-url>
cd amazonads-mcp

2. 安装依赖项：

npm install

3. 构建项目：

npm run build

配置

环境变量

创建 .env 文件或设置以下环境变量：

AMAZON_ADS_CLIENT_ID=your_client_id
AMAZON_ADS_CLIENT_SECRET=your_client_secret
AMAZON_ADS_REFRESH_TOKEN=your_refresh_token
AMAZON_ADS_REGION=NA  # Options: NA, EU, FE
AMAZON_ADS_SANDBOX=false  # Set to true for testing with sandbox API

Claude Desktop 配置

将此服务添加到 Claude Desktop 配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "amazonads": {
      "command": "node",
      "args": ["/absolute/path/to/amazonads-mcp/build/index.js"],
      "env": {
        "AMAZON_ADS_CLIENT_ID": "your_client_id",
        "AMAZON_ADS_CLIENT_SECRET": "your_client_secret",
        "AMAZON_ADS_REFRESH_TOKEN": "your_refresh_token",
        "AMAZON_ADS_REGION": "NA"
      }
    }
  }
}

使用示例

在 Claude Desktop 中完成配置后，你可以让 Claude：

• “显示我所有的 Amazon Ads 广告活动”
• “ID 为 12345 的广告活动在 1 月 1 日至 1 月 31 日期间的效果指标是什么？”
• “列出广告活动 12345 的所有关键词”
• “将关键词 67890 的竞价更新为 $1.50”
• “创建一个新的 Sponsored Products 广告活动，日预算为 $50”
• “显示广告活动 12345 中的所有商品广告”

开发

项目结构

amazonads-mcp/
├── src/
│   ├── index.ts              # Main MCP server implementation
│   └── amazon-ads-client.ts  # Amazon Ads API client
├── build/                     # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md

构建

npm run build

开发模式

监视更改并自动重新构建：

npm run watch

测试服务

直接运行服务：

npm start

此服务通过 stdio 通信，并等待 MCP 协议消息。

API 覆盖范围

此服务目前支持：

• Sponsored Products：全面支持广告活动、关键词和商品广告
• Sponsored Brands：广告活动管理（部分支持）
• Sponsored Display：广告活动管理（部分支持）
• 报告：基本效果指标（简化实现）

重要说明

1. 速率限制：Amazon Ads API 有速率限制。目前，客户端尚未实现速率限制逻辑。

2. Reporting API：get_campaign_performance 工具采用简化实现。若用于生产环境，应实现完整的异步报告流程：

   • 创建报告请求
   • 轮询报告完成状态
   • 下载并解析报告

3. 错误处理：API 错误会返回给调用方。请确保正确配置凭据，以避免身份验证错误。

4. 区域：请根据 Amazon Ads 账户设置正确的区域（NA、EU、FE）。

安全

• 切勿提交 .env 文件或暴露 API 凭据
• 应安全存储刷新令牌
• 考虑为生产环境实现凭据轮换

资源

• Amazon Ads API 文档
• Model Context Protocol 文档
• MCP TypeScript SDK

许可证

MIT

参与贡献

欢迎贡献！请随时提交 Pull Request。