技术文档摘要

<div align="center">

Amazon Ads API MCP SDK

使用 Amazon 广告 API 的 Model Context Protocol (MCP) SDK 构建基于AI的广告应用程序

由 Openbridge 热情打造

</div>

MCP 工具是什么？

可以将 MCP（模型上下文协议）视为一个在AI模型与外部系统（如Amazon Ads）之间进行翻译的角色。每个MCP工具就像一个遥控按钮，告诉AI如何与Amazon Ads互动。没有MCP工具，AI将不知道如何“与”Amazon Ads交流。

有了MCP工具：

• AI知道要调用的确切端点。
• AI可以安全地请求活动报告、预算或定位数据。
• 所有内容都是结构化的，因此AI不会通过随意猜测而破坏东西。

👉 简而言之：MCP工具 = 让AI能够与 Amazon Ads API 安全交互的工具箱。

🚀 Amazon Ads API MCP SDK 是什么？

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

✨ 主要功能

• 🔌 MCP 集成：完全符合 Model Context Protocol 的 AI 应用程序集成
• 🌍 多区域支持：自动路由的北美、欧洲和远东区域端点
• 📊 全面的 API 覆盖：活动管理、配置文件、报告、DSP、AMC 工作流等
• 📝 类型安全性：全面的类型提示支持 Pydantic 模型
• 🧪 生产就绪：包括测试、验证和错误处理

🎯 使用场景

Claude 桌面集成

• 活动管理：让 Claude 创建、更新或分析活动
• 性能洞察：获取基于AI的广告性能分析
• 预算优化：让 Claude 根据性能建议预算调整
• 创意测试：获得关于广告创意改进的建议
• 报告：按需生成自定义报告和见解

AI 应用

• 营销聊天机器人：构建能够管理 Amazon Ads 活动的对话式AI
• 自动化报告：基于AI的洞察和性能分析
• 智能预算管理：使用AI进行智能预算优化
• 创意优化：基于AI的广告创意测试和优化

企业服务

• 营销自动化平台：将 Amazon Ads 集成到现有的营销工具中
• 代理管理系统：多客户、多账户广告管理
• 电子商务集成：连接 Amazon Ads 和电子商务平台
• 分析仪表板：实时广告性能监控

开发者工具

• API 封装器：为特定用途创建自定义SDK
• 测试框架：Amazon Ads 集成的自动化测试
• 开发工具：本地开发和调试实用工具

📚 Amazon Ads MCP 包含什么？

MCP 服务器对已发布的 Amazon Ads API 提供了广泛的覆盖。每个都对应于 Amazon Ads API 中的一组操作。这包括新的 Amazon Ads API v1 的活动管理服务，导出，Amazon 营销云等等。

以下是一些代表性的 Amazon API 服务列表：

• 账户
• 受众
• 报告
• 品牌指标
• 赞助产品
• 赞助品牌
• 赞助展示
• Amazon DSP
• Amazon 归因
• 推荐和洞察
• 创意
• 更改历史
• 数据提供商
• 产品
• 统一预审核
• 审核
• Amazon 营销流
• 地点
• 导出
• 媒体规划

安装

我们推荐使用 🐳 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

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

配置

Amazon Ads 要求所有对 API 的调用都需要授权。如果您不确定这意味着什么，您应该阅读 Amazon 文档：

• Amazon Ads API 入门概述：https://advertising.amazon.com/API/docs/en-us/guides/onboarding/overview
• 开始使用 Amazon Ads API：https://advertising.amazon.com/API/docs/en-us/guides/get-started/overview

有两种途径连接到 API；

1. 自带应用 (BYOA)
2. 利用合作伙伴应用

自带 Amazon Ads API 应用

如果您有自己的 Amazon Ads API 应用，或者想要创建一个，过程如下所述。

1. 在 Amazon 注册您的应用

1. 访问 Amazon 开发者控制台
2. 创建或选择您的 Login with Amazon 应用
3. 记录您的 Client ID 和 Client Secret
4. 设置您的回调 URL 为 "允许返回的 URL"。这是您运行此服务器的地方：
   • 对于生产环境：https://your-server.com/auth/callback
   • 对于本地开发：http://localhost:8000/auth/callback

一旦您的应用被 Amazon 安全并批准，您需要客户端 ID 和密钥：

# Amazon Ads API 凭证（必需）
AMAZON_AD_API_CLIENT_ID="your-client-id"
AMAZON_AD_API_CLIENT_SECRET="your-client-secret"

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

AUTH_METHOD=direct

完成 OAuth 流程

为了授权您的连接到 Amazon，您需要作为最终用户完成 OAuth 流程。首先，您需要设置您的区域。授权发生在区域级别，不设置区域可能会导致失败。服务器默认为 na 区域。您可以手动设置区域使用工具 set_active_region。

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

示例提示："将我的当前区域设置为 eu"

第一步：启动 OAuth

要连接到 Amazon Ads API，您使用 MCP 工具来启动您的 OAuth 流程

• 工具：start_oauth_flow
• 示例提示："开始我的 OAuth 流程"

<img src="images/step1.png" alt="步骤 1" style="max-width: 600px;">

第二步：重定向到 Amazon Ads

在这个例子中，您会被提示点击链接，该链接会在浏览器窗口中打开，并要求在 Amazon 进行审批。

<img src="images/step2.png" alt="步骤 2" style="max-width: 600px;">

第三步：批准请求

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

<img src="images/step3.png" alt="步骤 3" style="max-width: 600px;">

第四步：成功

如果一切顺利，您将看到成功响应。您可以关闭浏览器窗口并回到客户端。如果看到其他内容，请尝试重新执行流程并确认所有配置元素正确无误

<img src="images/step4.png" alt="步骤 4" style="max-width: 600px;">

第五步：确认

要确认您的 MCP 服务器已连接到 Amazon Ads API，请检查您的 OAuth 状态

• 工具：check_oauth_status
• 示例提示："检查我的 OAuth 状态"

<img src="images/step5.png" alt="步骤 5" style="max-width: 600px;">

现在您可以开始与 Amazon Ads API 系统交互了！

合作伙伴应用：令牌认证

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

Openbridge 合作伙伴应用

作为 Ads API 合作伙伴应用提供商，Openbridge 提供了一个通往 Amazon Ads API 的现成网关。您登录到您的 Openbridge 账户，分配一个令牌，然后在客户端配置中设置您的令牌（见下文）。

首先，设置 Openbridge 作为身份验证方法：

AUTH_METHOD=openbridge

这就是服务器配置的内容。要访问服务器，您需要配置客户端，如 Claude Desktop，直接传递令牌。（参见 示例 MCP 客户端：连接 Claude Desktop）

授权的 Amazon 账户

您的 Amazon 授权存储在 Openbridge 中。您客户端的第一步是请求当前的身份："列出我的远程身份"。接下来，您会告诉 MCP 服务器使用这些身份之一："将我的远程身份设置为 <>"。然后您可以询问 MCP 列出与该账户关联的所有 Amazon Ad 配置文件。如果没有看到列出的广告商，设置不同的身份。

设置您的 Amazon Ads 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-management
• 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

您会注意到有些被分成更小的组合。例如，Amazon Marketing Cloud 有多个包；amc-ad-audience，amc-administration，amc-rule-audience 和 amc-workflow。这样做是为了创建效率和优化，减少许多AI客户端中的上下文限制。

理解 Amazon Ads MCP 工具

Amazon Ads MCP 工具具有前缀（如 cp_ 表示 Campaign Performance 或 amc_ 表示 Amazon Marketing Cloud），以帮助组织特定的 Ads API 操作。

示例前缀：

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

这将转化为与可用 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 — 检查工作流状态

用户会看到这样的工具：

• "列出我的 Amazon Ads 活动"
  → Claude 使用：cp_listCampaigns

• "创建一个 AMC 工作流"
  → Claude 使用：amc_createWorkflow

• "导出我的赞助产品广告数据"
  → Claude 使用：export_createAdExport

广告商配置文件及区域

设置您的广告商配置文件

根据 Amazon 的说法：配置文件在 Amazon Ads API 中起着关键作用，确定给定调用的管理范围。配置文件ID是访问特定市场中广告商数据和服务所需的基本凭证。

您可能不知道授权授予您访问哪些配置文件。您可以列出所有可访问的广告配置文件：

• 工具：ac_listProfiles
• 示例提示："列出我的广告商配置文件ID"

响应包括配置文件详细信息：

• profileId, 国家代码, 货币代码
• 日预算, 时区
• 账户信息（类型：卖家/供应商/代理）

假设您的列表包含配置文件ID 1043817530956285。您可以通过获取配置文件详细信息来确认这是您想要使用的配置文件。

• 工具：ac_getProfile
• 示例提示："获取我的 profile_id: 1043817530956285 的详细信息"

假设这是您想要使用的配置文件，您需要 设置 Amazon 要求用于 API 调用的配置文件：

• 工具：set_active_profile
• 示例提示："将我的活动配置文件ID设置为 1043817530956285"

当您设置配置文件时，它决定了：

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

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

大多数对 Amazon Ads API 的调用都需要一个区域。每个 广告商配置文件ID 都与特定区域/市场的广告账户相关联。

区域是广告商配置文件的一部分。当您使用 set_active_profile 设置广告商配置文件时，它会自动设置与配置文件相关的区域。

• 工具：set_active_profile

示例提示："将我的活动广告商配置文件设置为 111111111111"

由于配置文件ID 111111111111 基于 na，区域将根据配置文件区域设置。

设置活动区域

Amazon Ads 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

当您设置一个区域时，系统会自动：

1. 更新 API 端点 - 将 API 调用路由到正确的区域端点
2. 更新 OAuth 端点 - 使用正确的区域刷新令牌端点
3. 清除缓存的令牌 - 确保新区域的新鲜身份验证
4. 保留其他设置 - 保持配置文件ID和身份设置不变

重要提示：避免区域不匹配：如果您尝试设置与您的广告商配置文件无关的区域，Ads API 将拒绝您的请求。例如，如果配置文件ID与 na 关联，而您手动将区域设置为 eu，则会导致 API 请求失败。

获取活动区域

如果您不确定设置了哪个区域，可以检查区域

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

示例提示："我的当前活动区域是什么？"

示例 MCP 客户端：连接 Claude Desktop

导航到连接器设置

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

编辑您的 Claude Desktop 配置文件：

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

在此示例中，我们将展示如何