金大哥 - amazon_ads_mcp MCP 详情

article

README

🚀 Amazon Ads API MCP SDK

借助适用于亚马逊广告API的模型上下文协议（MCP）SDK，构建由人工智能驱动的广告应用程序

由 Openbridge 用心 + 咖啡打造

🚀 快速开始

MCP工具是什么？

可以将MCP（模型上下文协议）视为人工智能模型与外部系统（如亚马逊广告）之间的翻译器。每个MCP工具就像一个遥控器按钮，指示人工智能如何与亚马逊广告进行交互。如果没有MCP工具，人工智能将不知道如何与亚马逊广告“对话”。

借助MCP工具：

人工智能知道要调用的确切端点。
人工智能可以安全地请求广告活动报告、预算或定位数据。
一切都有结构，因此人工智能不会通过随机猜测而导致问题。

👉 简而言之：MCP工具是一个安全、标注清晰的工具包，使人工智能能够使用亚马逊广告API 开展工作。

什么是Amazon Ads API MCP SDK？

Amazon Ads API MCP SDK是一个开源实现，为创建由人工智能驱动的广告工具、聊天机器人和自动化服务提供了强大的基础。

✨ 主要特性

🔌 MCP集成：完全符合模型上下文协议，便于人工智能应用程序集成。
🌍 多区域支持：支持北美、欧洲和远东地区的端点，并可自动路由。
📊 全面的API覆盖：涵盖广告活动、广告资源、报告、DSP、AMC工作流程等。
📝 类型安全：全面支持Pydantic模型，并提供详细的类型提示。
🧪 生产就绪：包含测试、验证和错误处理功能。

🎯 使用场景

Claude桌面集成

广告活动管理：让Claude创建、更新或分析广告活动。
性能洞察：获取由人工智能驱动的广告性能分析。
预算优化：让Claude根据性能建议调整预算。
创意测试：获取广告创意改进建议。
报告：按需生成自定义报告和洞察。

人工智能应用程序

营销聊天机器人：构建能够管理亚马逊广告活动的对话式人工智能。
自动报告：由人工智能驱动的广告性能分析和洞察。
智能预算管理：使用人工智能进行智能预算优化。
创意优化：由人工智能驱动的广告创意测试和优化。

企业服务

营销自动化平台：将亚马逊广告集成到现有的营销工具中。
代理管理系统：多客户、多账户广告管理。
电子商务集成：将亚马逊广告与电子商务平台连接起来。
分析仪表盘：实时监控广告性能。

开发工具

API包装器：为特定用例创建自定义SDK。
测试框架：对亚马逊广告集成进行自动化测试。
开发工具：本地开发和调试工具。

📚 Amazon Ads MCP包含哪些内容？

MCP服务器广泛覆盖了亚马逊广告API中发布的内容。每个部分都与亚马逊广告API中的一组操作相对应。这包括诸如新亚马逊广告API v1中的广告活动管理服务、导出、亚马逊营销云等服务。

以下是MCP中各种亚马逊API服务的代表性列表：

账户
受众
报告
品牌指标
赞助商品
赞助品牌
赞助展示
亚马逊DSP
亚马逊归因
推荐与洞察
创意素材
更改历史记录
数据提供商
商品
统一预审核
审核
亚马逊营销流
位置
导出
媒体规划

📦 安装指南

我们建议使用 🐳 Docker 安装Amazon Ads API MCP：

docker pull openbridge/amazon-ads-mcp

复制环境模板：

cp .env.example .env

使用您的设置编辑 .env 文件。

使用Docker Compose启动服务器：

docker-compose up -d

服务器将在 http://localhost:9080 上可用。

查看日志：

docker-compose logs -f

停止服务器：

docker-compose down

有关完整的安装说明，包括验证、升级和开发人员设置，请参阅 安装指南。

配置

亚马逊广告要求所有对API的调用都经过授权。如果您不确定这意味着什么，您应该阅读亚马逊的文档：

亚马逊广告API入门概述：https://advertising.amazon.com/API/docs/en-us/guides/onboarding/overview
亚马逊广告API入门：https://advertising.amazon.com/API/docs/en-us/guides/get-started/overview

连接到API有两种途径：

自带应用程序（BYOA）
利用合作伙伴应用程序

自带亚马逊广告API应用程序

如果您有自己的亚马逊广告API应用程序，或者想创建一个，以下是详细的流程。

1. 在亚马逊注册您的应用程序

访问亚马逊开发者控制台。
创建或选择您的“使用亚马逊登录”应用程序。
记录您的 客户端ID 和 客户端密钥。
将您的回调URL设置为“允许的返回URL”。这是您运行此服务器的位置：
- 生产环境：https://your-server.com/auth/callback
- 本地开发环境：http://localhost:8000/auth/callback

一旦您的应用程序获得亚马逊的安全批准，您将需要客户端ID和密钥：

# 亚马逊广告API凭证（必需）
AMAZON_AD_API_CLIENT_ID="your-client-id"
AMAZON_AD_API_CLIENT_SECRET="your-client-secret"

确保这些信息在您的 .env 文件中。此外，确保在同一个 .env 文件中将授权方法设置为 direct：

AUTH_METHOD=direct

完成OAuth流程

要授权您与亚马逊的连接，您需要作为最终用户完成OAuth工作流程。首先，您需要设置您的区域。授权是在区域级别进行的，如果不设置区域可能会导致失败。服务器默认区域为 na。您可以使用工具 set_active_region 手动设置区域。

工具：set_active_region
参数：na | eu | fe

示例提示："Set my current region to eu"

步骤1：启动OAuth

要连接到亚马逊广告API，您可以使用MCP工具启动OAuth流程。

工具：start_oauth_flow
示例提示："Start my OAuth flow"

步骤2：重定向到亚马逊广告

在这个示例中，您会收到提示，点击链接将打开一个浏览器窗口，并请求在亚马逊上进行批准。

步骤3：批准请求

在浏览器窗口中，亚马逊会提示您批准连接请求。

步骤4：成功

如果一切顺利，您将看到成功响应。您可以关闭浏览器窗口并返回客户端。如果看到其他内容，请再次尝试该过程，并确认所有配置元素都正确。

步骤5：确认

要确认您的MCP服务器已连接到亚马逊广告API，请检查您的OAuth状态。

工具：check_oauth_status
示例提示："Check my OAuth status"

现在您可以开始与亚马逊广告API系统进行交互了！

合作伙伴应用程序：令牌认证

您可以配置您的客户端（如Claude），通过提供有效的访问令牌来进行认证。这适用于服务账户、长期有效的API密钥、CI/CD、认证单独管理的应用程序或其他非交互式认证方法。

Openbridge合作伙伴应用程序

作为广告API合作伙伴应用程序提供商，Openbridge提供了一个现成的网关来访问亚马逊广告API。您登录到Openbridge账户，生成一个令牌，然后在客户端配置中设置该令牌（见下文）。

首先，将Openbridge设置为认证方法：

AUTH_METHOD=openbridge

服务器配置就完成了。要访问服务器，您需要配置客户端（如Claude Desktop）直接传递令牌。（请参阅示例MCP客户端：连接Claude Desktop）

授权的亚马逊账户

您的亚马逊授权信息存储在Openbridge中。在客户端中的第一步是请求您当前的身份："List my remote identities"。接下来，您可以告诉MCP服务器使用其中一个身份："Set my remote identity to <>"。然后，您可以要求MCP列出与该账户关联的所有亚马逊广告资源："List all of my Amazon Ad profiles"。如果您没有看到列出的广告商，请设置不同的身份。

设置您的亚马逊广告MCP包

要激活，您需要设置一个以逗号分隔的包来加载。例如，要激活 profiles 和 amc-workflow，请按如下方式设置您的包环境：

AMAZON_AD_API_PACKAGES="profiles,amc-workflow"

以下是服务器中可用的工具包列表：

profiles
campaign-manage
accounts-manager-accounts
accounts-ads-accounts
accounts-portfolios
accounts-billing
accounts-account-budgets
audiences-discovery
reporting-version-3
brand-benchmarks
brand-metrics
stores-analytics
sponsored-products
sp-suggested-keywords
sponsored-brands-v4
sponsored-brands-v3
sponsored-display
dsp-measurement
dsp-advertisers
dsp-audiences
dsp-conversions
dsp-target-kpi-recommendations
amazon-attribution
audience-insights
forecasts
brand-store-manangement
partner-opportunities
tactical-recommendations
persona-builder
creative-assets
change-history
data-provider-data
data-provider-hashed
products-metadata
products-eligibility
unified-pre-moderation-results
moderation-results
amazon-marketing-stream
locations
exports-snapshots
marketing-mix-modeling
reach-forecasting
amc-administration
amc-workflow
amc-rule-audience
amc-ad-audience

您会注意到有些工具包被分成了更小的组。例如，亚马逊营销云有多个包：amc-ad-audience、amc-administration、amc-rule-audience 和 amc-workflow。这样做是为了提高效率和优化，减少许多人工智能客户端中的上下文限制。

理解亚马逊广告MCP工具

亚马逊广告MCP工具带有前缀（如 cp_ 表示广告活动性能，amc_ 表示亚马逊营销云），以帮助组织特定的广告API操作。

示例前缀：

cp_ → 广告活动/广告API
amc_ → 与AMC相关的API
dsp_ → DSP API
sd_ → 赞助展示
ams_ → 亚马逊营销流

这将转化为与可用的API操作相对应的工具集合：

广告活动管理 (`cp_`)

cp_listCampaigns — 列出所有广告活动
cp_getCampaign — 获取特定广告活动
cp_createCampaign — 创建新的广告活动
cp_updateCampaign — 更新广告活动
cp_archiveCampaign — 存档广告活动

赞助商品 (`sp_`)

sp_listProductAds — 列出商品广告
sp_createKeywords — 创建关键词
sp_updateBids — 更新关键词出价
sp_getNegativeKeywords — 获取否定关键词

AMC工作流程 (`amc_`)

amc_listWorkflows — 列出AMC工作流程
amc_executeWorkflow — 运行工作流程
amc_getWorkflowStatus — 检查工作流程状态

用户会看到如下工具：

"List my Amazon Ads campaigns"
→ Claude使用：cp_listCampaigns
"Create an AMC workflow"
→ Claude使用：amc_createWorkflow
"Export my sponsored products ads data"
→ Claude使用：export_createAdExport

广告商资源与区域

设置您的广告商资源

根据亚马逊的说法：资源在亚马逊广告API中起着至关重要的作用，它决定了给定调用的管理范围。资源ID是访问特定市场中广告商数据和服务所需的凭证。

您可能不知道您的授权可以访问哪些资源。您可以列出您的授权可以访问的所有广告资源：

工具：ac_listProfiles
示例提示："List my advertiser profile ids"

响应中包含资源详细信息：

资源ID、国家代码、货币代码
每日预算、时区
账户信息（类型：卖家/供应商/代理商）

假设您的列表中包含资源ID 1043817530956285。您可以通过获取资源详细信息来检查更多细节，以确认这是您要使用的资源。

工具：ac_getProfile
示例提示："Get the details for my profile_id: 1043817530956285"

假设这是您要使用的资源，您需要设置亚马逊API调用所需的资源：

工具：set_active_profile
示例提示："Set my active profile id to 1043817530956285"

当您设置资源时，它将决定：

您访问哪个账户的数据
报告的货币和时区
可用的广告活动/广告/关键词

资源ID将在您的会话期间在后台设置。如果您想切换到新的资源，请重复此过程。

大多数对亚马逊广告API的调用都需要一个区域。每个广告商资源ID 都与特定区域/市场中的广告账户相关联。

区域是广告商资源的一部分。当您使用 set_active_profile 设置广告商资源时，它将自动设置与该资源关联的区域。

工具：set_active_profile

示例提示："Set my active advertiser profile to 111111111111"

由于资源ID 111111111111 与 na 区域相关联，区域将根据资源区域进行设置。

设置活动区域

亚马逊广告MCP服务器包含用于管理API区域的工具，支持默认设置和动态设置，允许您在不重启服务器的情况下在北美（na）、欧洲（eu）和远东（fe）区域之间切换。

| 区域代码 | 名称 | API端点 | |------------|------|--------------| | na | 北美 | https://advertising-api.amazon.com | | eu | 欧洲 | https://advertising-api-eu.amazon.com | | fe | 远东 | https://advertising-api-fe.amazon.com |

当您设置区域时，系统会自动执行以下操作：

更新API端点 - 将API调用路由到正确的区域端点。
更新OAuth端点 - 使用该区域正确的令牌刷新端点。
清除缓存的令牌 - 确保为新区域进行全新的身份验证。
保留其他设置 - 保持资源ID和身份设置不变。

⚠️ 重要提示

避免区域不匹配：如果您尝试设置与您的广告商资源不关联的区域，广告API将拒绝您的请求。例如，如果一个资源ID与 na 区域相关联，而您手动将区域设置为 eu，就会造成不匹配，从而导致API请求失败。

获取活动区域

如果您不确定当前设置的区域，可以检查区域信息。

工具：get_active_region
返回：当前区域、端点和配置来源

示例提示："What is my current active region?"

💻 使用示例：连接Claude桌面

1. 导航到连接器设置

在浏览器中打开Claude，然后导航到设置页面。您可以通过点击您的个人资料图标，然后从下拉菜单中选择“设置”来访问此页面。进入设置后，在侧边栏中找到并点击“连接器”部分。这将显示您当前配置的连接器，并提供添加新连接器的选项。

2. 编辑Claude桌面配置文件

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

在这个示例中，我们展示了如何使用Openbridge API密钥使用Bearer令牌。将以下配置添加到您的 mcpServers 部分：

{
  "mcpServers": {
    "amazon_ads_mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "http://${HOSTNAME}:${PORT}/mcp/",
        "--allow-http",
        "--header",
        "Authorization:Bearer ${OPENBRIDGE_REFRESH_TOKEN}",
        "--header",
        "Accept:application/json,text/event-stream",
        "--debug"
      ],
      "env": {
        "MCP_TIMEOUT": "300",
        "HOSTNAME": "your_hostname",
        "PORT": "your_server_port",
        "MCP_TIMEOUT": "120000",
        "MCP_REQUEST_TIMEOUT": "60000",
        "MCP_CONNECTION_TIMEOUT": "10000",
        "MCP_SERVER_REQUEST_TIMEOUT": "60000",
        "MCP_TOOL_TIMEOUT": "120000",
        "MCP_REQUEST_WARNING_THRESHOLD": "10000",
        "OPENBRIDGE_REFRESH_TOKEN": "your_openbridge_token_here"
      }
    }
  }
}

注意：将 hostname、port 和 your_openbridge_token_here 替换为您实际的OpenBridge令牌。

⚠️ 重要提示

Cursor和Claude桌面（Windows）存在一个问题，当调用npx时，参数中的空格不会被转义，这会导致这些值被破坏。您可以使用 mcp-remote自定义头文档来解决这个问题。

配置可能如下所示：

{
  "mcpServers": {
    "amazon_ads_mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://${HOSTNAME}:${PORT}/mcp/",
        "--allow-http",
        "--header",
        "Authorization:${AUTH_HEADER}",
        "--header",
        "Accept: application/json, text/event-stream"
      ],
      "env": {
        "MCP_TIMEOUT": "300",
        "HOSTNAME": "your_hostname",
        "PORT": "your_server_port",
        "MCP_TIMEOUT": "120000",
        "MCP_REQUEST_TIMEOUT": "60000",
        "MCP_CONNECTION_TIMEOUT": "10000",
        "MCP_SERVER_REQUEST_TIMEOUT": "60000",
        "MCP_TOOL_TIMEOUT": "120000",
        "MCP_REQUEST_WARNING_THRESHOLD": "10000",
        "AUTH_HEADER": "Bearer <your_openbridge_token_here>"
      }
    }
  }
}

以下是另一个示例，如果您使用OAuth，则不需要 OPENBRIDGE_REFRESH_TOKEN：

{
  "mcpServers": {
    "amazon_ads_mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "http://localhost:9080/mcp/",
        "--allow-http"
      ],
      "env": {
        "MCP_TIMEOUT": "120000",
        "MCP_REQUEST_TIMEOUT": "60000",
        "MCP_CONNECTION_TIMEOUT": "10000",
        "MCP_SERVER_REQUEST_TIMEOUT": "60000",
        "MCP_TOOL_TIMEOUT": "120000",
        "MCP_REQUEST_WARNING_THRESHOLD": "10000"
      }
    }
  }
}

注意：有关与上述类似的各种Claude配置，请参阅 MCP Remote文档以获取最新设置/选项。

3. 重启Claude桌面

保存配置文件后，重启Claude桌面以加载新的MCP服务器。

⚠️ 上下文限制和活动MCP服务器工具

MCP工具的注册和使用可能会影响您的人工智能系统使用限制。使用限制控制您在特定时间段内可以与人工智能系统（如Claude）进行交互的程度。正如Anthropic所说，可以将使用的信息量/数据量视为消耗“对话预算”。该预算决定了在需要等待限制重置之前，您可以向人工智能客户端发送多少消息，或者可以工作多长时间。

MCP服务器工具会向模型的上下文提供元数据，如标题、描述、提示和模式。这些元数据会加载到大语言模型（LLM）的上下文窗口中，该窗口充当其短期工作内存。

每个客户端（如Claude）都有一个固定大小的上下文窗口。这定义了它在单次交互中可以处理的最大信息量，包括用户提示、系统指令、工具元数据和任何先前的消息。

您激活的工具越多，预先消耗的有限空间就越多。当您激活许多工具时，它们的组合模式和配置负载可能会显著占用这个上下文，您可能很快就会达到上下文上限。这时，您会开始看到关于超出聊天长度限制的错误或警告。

亚马逊广告MCP覆盖了整个API。因此，可能会有数百个工具！

工具越多，用户交互空间就越少：激活不必要的工具会减少实际提示或数据的可用空间。
从小处着手：仅激活当前任务所需的工具。您随时可以在以后添加更多工具。

如果您遇到意外的长度问题，请检查哪些工具处于活动状态。删除未使用的工具可以帮助减少上下文使用。

故障排除

服务器无法连接？

确保Docker容器正在运行：docker-compose ps
检查服务器日志：docker-compose logs -f
验证端口是否正确（默认为8765）

认证错误？

检查您的OpenBridge令牌是否有效。
确保令牌已正确设置在环境中。
验证您的亚马逊广告API访问权限。

Claude无法识别服务器？

在配置更改后重启Claude桌面。
如果MCP未激活，请在Claude桌面中“重新加载页面”。
检查JSON语法是否有效。
确保服务器名称完全匹配。

📄 许可证

本项目采用MIT许可证 - 有关详细信息，请参阅 LICENSE 文件。