Amazon Ads API MCP

亚马逊广告API MCP SDK

使用亚马逊广告API的模型上下文协议（MCP）SDK构建AI驱动的广告应用程序

*由...制作❤️ + ☕ 通过 Openbridge*

  

MCP注册表id （适用于显示稳定包名的客户端和目录）： io.github.KuudoAI/amazon_ads_mcp

目录

• 什么是MCP工具？
• 什么是亚马逊广告API MCP SDK？
• 快速启动
• 安装
• 配置 （身份验证、包、配置文件、区域）
• 下载报告和导出
• MCP客户端示例（克劳德桌面）
• 上下文限制
• 代码模式
• 工具审计
• 后台任务
• 故障排除
• 文档地图

什么是MCP工具？

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

使用MCP工具：

• AI知道要调用的确切端点。
• AI可以安全地请求活动报告、预算或目标数据。
• 一切都是结构化的，所以人工智能不会通过随机猜测来破坏事物。

👉 简而言之：MCP工具=一个安全、标记良好的工具包，让人工智能与 亚马逊广告API.

🚀 什么是亚马逊广告API MCP SDK？

亚马逊广告API MCP SDK是一个开源实现，为创建人工智能广告工具、聊天机器人和自动化服务提供了坚实的基础。

✨ 主要特点

• 🔌 MCP集成：完全符合AI应用程序集成的模型上下文协议
• 🌍 多区域支持：具有自动路由的NA、EU和FE区域端点
• 📊 API全面覆盖：活动、简介、报告、DSP、AMC工作流程等
• 📝 类型安全：完全支持Pydantic模型，并提供全面的类型提示
• 🧪 生产就绪：包括测试、验证和错误处理

🎯 用例

Claude桌面集成

• 活动管理：请Claude创建、更新或分析活动
• 性能洞察：获取基于人工智能的广告表现分析
• 预算优化：让克劳德根据绩效建议预算调整
• 创意测试：获取广告创意改进建议
• 报告：根据需要生成自定义报告和见解

人工智能应用

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

企业服务

• 营销自动化平台：将亚马逊广告整合到现有的营销工具中
• 机构管理系统：多客户、多账户广告管理
• 电子商务集成：将亚马逊广告与电子商务平台连接起来
• 分析仪表板：实时广告绩效监控

开发者工具

• API包装：为特定用例创建自定义SDK
• 测试框架：自动测试亚马逊广告集成
• 开发工具：本地开发和调试实用程序

为什么这个广告MCP不同

其他亚马逊广告MCP也走上了幸福的道路。当代理商犯下合理的错误时，他们就会崩溃，亚马逊的Ads API比几乎任何其他大型API表面都有更合理的错误。v1报告目录使用与v3不同的词汇表。文档分散在迁移的几代人中。同一字段可以有三个合理的名称，具体取决于代理或人类接受的训练教程。

你以前也有过这种感觉

即使你从未将其视为一个单一的问题，你也知道这些症状：

• “紧凑的谈话……”就在你到达某个地方时
• 任务中期“已达到使用限制”，令牌无任何显示
• “超出上下文窗口”重新开始，重新解释一切
• 特工悄悄地忘记了三圈前想出的解决办法
• 五次工具调用，其中四次重试，没有一次取得进展
• 第三次将相同的错误重新粘贴到聊天中

这不是愚蠢的模型。这就是 API表面燃烧上下文 模糊的错误会触发抖动，抖动会填满窗口，窗口会填满，所有有用的东西都会被驱逐。代理商往返4到12次：错误的字段名称、错误的身体形状、错误的过滤运算符、错误的日期位置、错误的广告商帐户格式。

在这里，错误的动作会返回正确的动作

此服务器是围绕不同的前提构建的： 错误表面是文档表面。 每一次失败都是一次教学机会，服务器的设计使下一次尝试比上一次更聪明，无论是对于同一个代理还是下一个代理，都不需要重新训练、提示更新或记忆技巧。

• 服务器告诉出了什么问题 *为什么* 你搞错了
• 每次失败都会转化为纠正措施——模型只需读取提示并继续
• 一个五工具调用调试弧折叠成一个两调用校正弧
• 一周后，同样的错误不会重新烧录上下文，因为验证器、别名表和弃用的形状表仍然存在
• 没有断章取义的部落知识可以忘记

每次失败都比上次便宜。每个代理都从同一个权威来源学习。每次重试都有方向。这种复合是智能代理解决方案在实践中的样子。

一切都是边缘案例，你可以帮忙

我们不会抓住每一个边缘案例。亚马逊的API表面是巨大的，迁移历史是混乱的，现实世界中的失败比任何人都能预料到的更具创造性。我们承诺的是 策略 错误应该教导我们，文档应该存在于代理实际接触的表面中，每一个错误的举动都应该使下一步更容易。

如果你遭遇了失败，而信封没有帮助；模糊的暗示、错误的建议、完全没有暗示，这正是我们想要的反馈。 打开一个问题，贴上信封，告诉我们你的期望。 该策略的有效性取决于其涵盖的案例。

快速启动

1. git clone https://github.com/KuudoAI/amazon-ads-mcp.git && cd amazon-ads-mcp
2. cp .env.example .env 并添加凭据（请参阅 配置).
3. docker compose up -d
4. 将您的MCP客户端连接到 `http://localhost:

/mcp/ — .env.example 套 **PORT=9080** （覆盖 .env` 如果需要）。

OAuth步骤、客户端JSON示例和完整的变量引用： 配置 在......下面 安装.md，以及 代理商.md.

📚 亚马逊广告MCP包括哪些内容？

MCP服务器反映了亚马逊广告API表面的广泛覆盖范围。每个启用的包映射到一组API操作。这包括 活动管理（亚马逊广告API v1）, 出口, 亚马逊营销云，以及更多。

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

• 账户
• 观众
• 报告
• 品牌指标
• 赞助商品
• 赞助品牌
• 赞助展示
• 亚马逊DSP
• 亚马逊归因
• 建议和见解
• 创意作品
• 变更历史
• 数据提供程序
• 产品
• 统一预审核
• 节制
• 亚马逊营销流
• 位置
• 出口
• 媒介计划
• 亚马逊广告API v1

🧪 亚马逊广告API v1

亚马逊广告API v1代表了亚马逊广告API的一种重新构想的方法，从头开始构建，通过一个通用模型在所有亚马逊广告产品中提供无缝体验。这种通用模型的一个主要好处是提高了与客户端库生成器等代码生成工具的兼容性。

⚠️ Beta通知：这些API目前在亚马逊处于测试阶段。功能和端点可能会发生变化。在生产中谨慎使用。

要激活Ads API v1软件包，请将其添加到您的 AMAZON_AD_API_PACKAGES 环境变量：

# Example: Enable the merged Ads API v1 ALL surface
AMAZON_AD_API_PACKAGES="profiles,ads-api-v1-all"

有关更多信息，请参阅亚马逊的 活动管理概述.

安装

我们建议运行亚马逊广告API MCP🐳 码头工人。从该存储库构建映像（不支持 docker pull 对于此处的第三方注册表映像，请使用 Dockerfile 和 docker-compose.yaml 在回购中）。

git clone https://github.com/KuudoAI/amazon-ads-mcp.git
cd amazon-ads-mcp

复制环境模板：

cp .env.example .env

编辑 .env 使用您的设置（包括 PORT 如果更改默认值）。

使用Docker Compose启动服务器（构建和标签 amazon-ads-mcp:latest 每 docker-compose.yaml):

docker compose up -d

服务器侦听从映射的主机端口 PORT 在 .env (.env.example 用途 9080).

检查日志：

docker compose logs -f

停止服务器：

docker compose down

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

配置

运营商/自营商： 按照以下步骤和 .env 文件。 聊天用户 服务器连接后，主要通过提示进行交互；浏览 广告商简介和地区 用于配置文件和区域行为。

Amazon Ads要求所有对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；

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

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

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

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

1. 去 亚马逊开发者控制台
2. 创建或选择您的亚马逊登录应用程序
3. 注意你的 Client ID 和 Client Secret
4. 将您的回调URL设置为“允许返回URL”。这必须与此MCP服务器的HTTP侦听器的主机和端口匹配（请参阅 PORT 在 .env; .env.example 用途 9080):

- 生产： https://your-server.com/auth/callback - 对于当地发展： http://localhost: /auth/callback （例如。 http://localhost:9080/auth/callback)

一旦您的应用程序得到亚马逊的保护和批准，您将需要客户端ID和密码：

# Amazon Ads API Credentials (required)
AMAZON_AD_API_CLIENT_ID="your-client-id"
AMAZON_AD_API_CLIENT_SECRET="your-client-secret"

确保这些都在你的 .env 文件。此外，请确保将授权方法设置为 direct 同样地 .env:

AUTH_METHOD=direct

完整的OAuth流程

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

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

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

第一步：启动OAuth

要连接到Amazon Ads API，请使用MCP工具启动OAuth流

• 工具： start_oauth_flow
• 示例提示： *“启动我的OAuth流”*

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

在此示例中，系统会提示您单击链接，该链接将打开浏览器窗口并在亚马逊上请求批准。

步骤3：批准请求

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

第四步：成功

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

步骤5：确认

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

• 工具： check_oauth_status
• 示例提示： *“检查我的OAuth状态”*

您已经准备好开始与亚马逊广告API系统交互了！

合作伙伴应用程序：令牌身份验证

您可以像Claude一样配置您的客户端，通过提供有效的访问令牌来使用身份验证。这最适用于服务帐户、长期使用的API密钥、CI/CD、单独管理身份验证的应用程序或其他非交互式身份验证方法。

Openbridge合作伙伴应用程序

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

首先，将Openbridge设置为auth方法：

AUTH_METHOD=openbridge

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

授权亚马逊帐户

您的亚马逊授权驻留在Openbridge中。您在客户中的第一步是请求您当前的身份： "List my remote identities"接下来，您将告诉MCP服务器使用以下身份之一： "Set my remote identity to <>"。然后，您可以要求MCP List all of my Amazon Ad profiles 链接到该帐户。如果您没有看到列出的广告商，请设置其他身份。

设置您的亚马逊广告MCP套餐

要激活特定的包，请设置逗号分隔的包列表。对于具有统一Ads API v1覆盖范围的精简默认：

• AMAZON_AD_API_PACKAGES="profiles,accounts-ads-accounts,reporting-version-3,amc-workflow,ads-api-v1-all"

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

• profiles
• test-account
• forecasts
• brand-stores-management
• 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
• partner-opportunities
• tactical-recommendations
• persona-builder
• creative-assets
• change-history
• data-provider-data
• 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
• ads-api-v1-sp *（测试版）*
• ads-api-v1-sb *（测试版）*
• ads-api-v1-dsp *（测试版）*
• ads-api-v1-sd *（测试版）*
• ads-api-v1-st *（测试版）*
• ads-api-v1-all
• ads-api-v1-beta *（测试版）*

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

了解亚马逊广告MCP工具

亚马逊广告MCP工具有前缀（如 cm_ 用于活动管理或 amc_ 用于亚马逊营销云），以帮助组织特定的Ads API操作。

前缀示例：

• cm_ → 活动/广告API
• amc_ → AMC相关API
• dsp_ → DSP API
• sd_ → 赞助展示
• ams_ → 亚马逊营销流
• spv1_ → 赞助产品v1 *（测试版）*
• sbv1_ → 赞助品牌v1 *（测试版）*
• dspv1_ → 亚马逊DSP v1 *（测试版）*
• sdv1_ → 赞助展示v1 *（测试版）*
• stv1_ → 赞助电视v1 *（测试版）*

这将转化为与可用的API操作一致的工具集合：

活动管理(cm_)

• cm_QueryCampaign --查询活动
• cm_CreateCampaign --创建活动
• cm_UpdateCampaign --更新活动
• cm_DeleteCampaign --删除活动
• cm_QueryAdGroup --查询广告组

赞助产品(sp_)

• sp_listProductAds --列出产品广告
• sp_createKeywords --创建关键字
• sp_updateBids --更新关键字出价
• sp_getNegativeKeywords --获取负面关键词

AMC工作流程(amc_)

• amc_listWorkflows --列出AMC工作流
• amc_executeWorkflow --运行工作流
• amc_getWorkflowStatus --检查工作流状态

用户将看到以下工具：

• “列出我的亚马逊广告活动”\

→ 克劳德使用： cm_QueryCampaign

• “创建AMC工作流”\

→ Claude使用的工具包括 amc_executeWorkflow （发现后；确切名称取决于您启用的软件包）

• “导出我的赞助产品广告数据”

→ 克劳德使用： export_createAdExport

📥 下载报告和导出

当工具从亚马逊获取报告或导出时，它们 将文件下载到运行MCP服务器的计算机上 （服务器主机上的本地磁盘——Docker卷、VM或裸机——除非服务器在那里运行，否则不是你的笔记本电脑）。默认的基本目录是 ./data （用覆盖 AMAZON_ADS_DOWNLOAD_DIR).文件按以下方式组织 data/profiles/{profile_id}/….

MCP工具列出这些服务器端文件和构建URL；然后客户端将字节拉过来 超文本传输协议 (GET /downloads, GET /downloads/{relative-path}).在这些流中，没有任何东西在不首先撞击服务器存储的情况下直接从亚马逊流入MCP客户端。

使用HTTP传输 下载：运行 --transport http （或端口9080上的Docker）。 标准 模式未注册 /downloads，以及 get_download_url 该工具在没有HTTP的情况下返回错误。

报告与出口

• V3异步报告： 使用OpenAPI工具 createAsyncReport （POST）以创建， getAsyncReport （GET）查询状态，然后 download_export 保存已完成的文件 在服务器上 进入配置文件存储。
• 出口（如广告出口）： 使用OpenAPI工具创建作业（例如。 export_CampaignExport)，投票给 export_GetExport，然后致电 download_export 使用完成URL，因此文件为 从亚马逊获取并写入服务器 （存储布局与报告相同）。

工作流程

1. 设置活动配置文件 (set_active_profile)因此存储和HTTP访问是有作用域的。
2. 创建作业： 使用适当的OpenAPI工具创建报告或导出。
3. 完成投票： 使用相应的GET工具检查状态，直到 COMPLETED.
4. 下载： 呼叫 download_export 使用已完成响应中的下载URL。
5. 发现或链接： MCP工具 list_downloads 和 get_download_url.
6. 获取字节数： 超文本传输协议 GET 在步骤5的URL上（浏览器、curl等）。

配置文件文件夹下的子路径取决于报告/导出类型（例如 reports/…, exports/…).URL看起来像 http://localhost:9080/downloads/{relative-path} 哪里 {relative-path} 火柴 list_downloads （说明性示例： reports/async/some-report.json.gz).

直接HTTP(curl): /downloads 使用 活动配置文件 在正在运行的服务器中（在该过程中通过MCP设置的服务器）。如果你看到 No active profile，呼叫 set_active_profile 首先通过MCP对同一服务器进行攻击。当没有配置身份验证管理器时，一个数字 ?profile_id= 查询参数可能会被接受——请参阅您的部署设置。

示例提示

HTTP下载API

# List available downloads (paths and URLs are profile-scoped)
curl http://localhost:9080/downloads

# Optional filter
curl 'http://localhost:9080/downloads?type=reports'

# Download one file (example path — use paths from list_downloads)
curl -O 'http://localhost:9080/downloads/reports/async/example-report.json.gz'

# If AMAZON_ADS_DOWNLOAD_AUTH_TOKEN is set
curl -H "Authorization: Bearer your-token" -O 'http://localhost:9080/downloads/exports/campaigns/example-export.json'

配置文件隔离

• 文件位于 data/profiles/{profile_id}/.
• 下载工具和 /downloads 只看 活跃的 配置文件。
• 首先设置配置文件： *“将我的活动个人资料设置为123456789”*.
• 外部的旧文件 profiles/ 使用配置文件作用域模式时未列出；把它们移到下面 data/profiles/{profile_id}/ 访问。

广告商简介和地区

设置您的广告商个人资料

根据亚马逊： *概要文件通过确定给定调用的管理范围，在Amazon Ads API中发挥着至关重要的作用。个人资料ID是访问特定市场中广告商数据和服务所需的凭证。*

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

• 工具： ac_listProfiles
• 示例提示： *“列出我的广告商个人资料ID”*

警告： 大型帐户可以返回可能超过客户端上下文限制的非常大的配置文件列表。更喜欢这些有界的发现工具：

• 工具： summarize_profiles — *“总结我的广告商简介”*
• 工具： search_profiles — *“在美国查找Acme的个人资料”*
• 工具： page_profiles — *“显示前20个英国简介”*
• 工具： refresh_profiles_cache — *“刷新我的配置文件列表缓存”*

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

• 精通国家代码、货币代码
• 每日预算，时区
• accountInfo（类型：卖家/供应商/代理）

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

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

假设这是您要使用的配置文件，您需要 集 Amazon对API调用所需的配置文件：

• 工具： set_active_profile
• 示例提示： *“将我的活动个人资料id设置为 1043817530956285"*

设置配置文件时，它会确定：

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

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

大多数对Amazon Ads API的调用都需要一个Region。每 广告商个人资料ID 与特定地区/市场中的广告账户相关联。

该地区是广告商个人资料的一部分。当您使用设置广告商个人资料时 set_active_profile，它将自动设置与配置文件关联的区域。

• 工具： set_active_profile

示例提示： *“将我的活跃广告商个人资料设置为 111111111111"*

由于配置文件ID 111111111111 总部位于 na，将基于配置文件区域设置区域。

设置活动区域

Amazon Ads MCP服务器包括用于将API区域作为默认和动态管理的工具，允许您在北美之间切换(na)，欧洲(eu)和远东(fe)无需重新启动服务器。

设置区域时，系统会自动：

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

重要提示：避免区域不匹配: *如果您试图设置与您的广告客户个人资料不相关的区域，Ads API将拒绝您的请求。例如，如果将配置文件ID附加到 na 然后手动将区域设置为 eu，您创建了一个不匹配，这将导致API请求失败。*

获取活动区域

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

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

示例提示： *“我目前活跃的地区是哪里？”*

MCP客户端示例：连接Claude桌面

导航到“连接器设置”

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

编辑您的Claude Desktop配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json\ 视窗: %APPDATA%\Claude\claude_desktop_config.json\ Linux: ~/.config/Claude/claude_desktop_config.json

在这个例子中，我们展示了如何使用Openbridge API密钥来使用承载令牌。将此配置添加到您的 mcpServers 章节：

{
  "mcpServers": {
    "amazon_ads_mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "http://${HOSTNAME}:${PORT}/mcp/",
        "--allow-http",
        "--header",
        "Authorization:Bearer ${OPENBRIDGE_API_KEY}",
        "--header",
        "Accept:application/json,text/event-stream",
        "--debug"
      ],
      "env": {
        "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_API_KEY": "your_openbridge_token_here"
      }
    }
  }
}

备注：替换 hostname, port 和 your_openbridge_token_here 使用您的实际OpenBridge令牌。

重要：Cursor和Claude Desktop（Windows）有一个错误，当它调用npx时，args中的空格没有转义，这最终会破坏这些值。您可以使用以下方法解决此问题： mcp远程自定义头文件.

配置看起来像这样：

{
  "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": {
        "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 "
      }
    }
  }
}

这是另一个例子，如果您正在使用OAuth，则可以使用它，因为 OPENBRIDGE_API_KEY 不需要：

{
  "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远程文档 获取最新设置/选项。*

重新启动克劳德桌面

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

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

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

MCP服务器工具为模型的上下文提供元数据，如标题、描述、提示和模式。此元数据被加载到LLM的上下文窗口中，该窗口充当其短期工作记忆。

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

你激活的工具越多，前期消耗的有限空间就越多。当您激活许多工具时，它们的组合模式和配置有效负载可能会严重消耗此上下文，您可能会很快达到上下文上限。此时，您将开始看到有关超过聊天长度限制的错误或警告。

亚马逊广告MCP覆盖整个API。因此，可能会有100多种工具！

• 更多的工具=更少的用户交互空间：激活不必要的工具会减少实际提示或数据的可用空间。
• 从小处着手：只激活当前任务所需的内容。您可以稍后添加更多内容。

如果您遇到意外的长度问题，请查看哪些工具处于活动状态。修剪未使用的内容可以帮助最大限度地减少上下文使用。

代码模式

代码模式是一种显著减少工具令牌消耗的功能。Code Mode没有预先将每个工具模式加载到LLM的上下文中，而是用四个轻量级元工具替换了整个目录。LLM根据需要发现工具，并通过沙盒Python执行它们。

代币影响

*典型默认大小目录的示例性比较；实际工具数量和令牌使用取决于 AMAZON_AD_API_PACKAGES、服务器版本和标记器。*

运作原理

代码模式使用4阶段发现模式：

Stage 1: tags          → Browse categories: "campaign-management (20), accounts (14), ..."
Stage 2: search        → Find tools: search("campaigns") → cm_listCampaigns, cm_createCampaign, ...
Stage 3: get_schema    → Get parameters: get_schema("cm_listCampaigns") → full input schema
Stage 4: execute       → Run code: sandboxed Python with await call_tool("cm_listCampaigns", {...})

所有200多种工具仍然完全可用。LLM只是按需发现和调用它们，而不是预先加载每个模式。

激活代码模式

代码模式默认为 CODE_MODE=true。要在上下文中使用完整的工具目录，请设置：

CODE_MODE=false

Docker Compose --添加到您的 environment 章节：

environment:
  - CODE_MODE=false

Docker运行 （将主机端口映射到容器 PORT例如9080）：

docker run -d --env-file .env -e CODE_MODE=false -e PORT=9080 -p 9080:9080 amazon-ads-mcp:latest

本地开发 （入口点是 python -m amazon_ads_mcp.server，其运行MCP服务器模块）：

CODE_MODE=false uv run python -m amazon_ads_mcp.server --transport http --port 9080

配置选项

使用代码模式

启用后，您的MCP客户端（Claude Desktop、Claude Code等）将只看到四个工具，而不是完整的目录。

浏览可用类别：

*“有哪些可用的工具类别？”*

LLM电话 tags 并看到以下类别 campaign-management, sponsored-products, programmatic-dsp, accounts, reporting等等。

查找特定工具：

*“查找管理活动的工具”*

LLM电话 search("campaigns") 并获取具有简短描述的匹配工具名称。

获取工具详细信息：

*“显示创建活动的参数”*

LLM电话 get_schema("cm_CreateCampaign") 并获取完整的输入模式。

执行操作：

*“列出我启用的活动”*

LLM电话 execute 使用Python代码：

result = await call_tool("cm_QueryCampaign", {
    "body": {"stateFilter": {"include": ["ENABLED"]}}
})

工具类别

当LLM来电时 tags，它看到了从API前缀映射的可供人修改的类别：

何时使用代码模式

在以下情况下使用代码模式：

• 您激活了许多工具包，并且达到了上下文限制
• 您希望为对话和数据分析提供最大的上下文空间
• 您的MCP客户端支持工具发现模式（Claude Desktop、Claude Code）

在以下情况下使用标准模式：

• 您激活了少量软件包（1-3个）
• 您需要尽可能快的工具调用（无发现步骤）
• 您的工作流程重复使用相同的几个工具

验证代码模式

使用启动服务器后 CODE_MODE=true，验证它是否处于活动状态：

# Check server logs for confirmation
docker logs  2>&1 | grep "Code mode"
# Expected: "Code mode active: 4 meta-tools exposed (tags, search, get_schema, execute)"

在您的MCP客户端中，您应该只看到四个工具： tags, search, get_schema，以及 execute。如果您看到完整的工具目录，则代码模式未处于活动状态——请检查您的环境变量。

工具审核

使用 tool_audit 测量工具目录和代码模式行为的令牌占用空间。

基线审计

.venv/bin/python -m amazon_ads_mcp.tool_audit \
  --url http://127.0.0.1:9080/mcp \
  --limit 20

JSON输出：

.venv/bin/python -m amazon_ads_mcp.tool_audit \
  --url http://127.0.0.1:9080/mcp \
  --format json \
  --limit 0 \
  > /tmp/tool_audit.json

代码模式探测审核

当代码模式处于活动状态时，使用探测模式估算按需模式获取成本：

.venv/bin/python -m amazon_ads_mcp.tool_audit \
  --url http://127.0.0.1:9080/mcp \
  --format json \
  --limit 0 \
  --code-mode-probe \
  --probe-limit 50 \
  --probe-queries "campaign,ad,report,profile,dsp,amc,brand,targeting" \
  > /tmp/tool_audit_code_mode.json

快速比较

jq '{tool_count,total_tool_tokens,context_window_percent}' /tmp/tool_audit.json
jq '{tool_count,total_tool_tokens,context_window_percent,code_mode_probe}' /tmp/tool_audit_code_mode.json

关键字段：

• total_tool_tokens：前端令牌加载来自 tools/list
• context_window_percent：已配置上下文窗口的共享
• code_mode_probe.total_schema_tokens：代码模式下采样模式获取令牌的总成本
• code_mode_probe.avg_schema_tokens：每个提取的架构的平均令牌成本

后台任务

许多亚马逊广告API操作都是长期运行的——报告生成、导出创建、AMC工作流执行、受众处理和DSP测量研究可能需要几秒钟到几分钟的时间。后台任务允许这些操作在不阻止对话的情况下运行。

运作原理

后台任务包括 默认启用当客户端请求后台执行任何工具时：

1. 开始：工具立即返回任务ID
2. 轨道：客户端按服务器建议的时间间隔轮询进度更新
3. 检索：客户端在任务完成时获取结果

服务器中的所有异步工具都支持自动后台执行。客户端根据每次调用决定是在前台（等待结果）还是在后台（获取任务ID，稍后轮询）运行工具。

内置工作流工具

这些工具编排多步骤工作流（下载和HTTP访问服务器端文件）：

这些工具包括进度报告，因此客户可以跟踪工作流的每个阶段。

配置

要禁用后台任务，请执行以下操作：

ENABLE_TASKS=false

Docker Compose --添加到您的 environment 章节：

environment:
  - ENABLE_TASKS=false

后端

默认情况下，服务器使用内存中的任务后端。在服务器进程的生命周期内跟踪任务。如果服务器重新启动，正在进行的任务将丢失。

对于跨重启的持久任务跟踪，请配置Redis后端：

FASTMCP_DOCKET_URL=redis://localhost:6379

示例提示

故障排除

服务器未连接？

• 确保Docker容器正在运行： docker compose ps
• 检查服务器日志： docker compose logs -f
• 验证主机端口是否匹配 PORT 在 .env (.env.example 用途 9080；您的映射必须匹配）

身份验证错误？

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

克劳德没认出服务器？

• 配置更改后重新启动Claude Desktop
• 如果MCP未处于活动状态，则在Claude Desktop中“重新加载页面”
• 检查JSON语法是否有效
• 确保服务器名称完全匹配

文档地图

📄 许可证

该项目根据MIT许可证获得许可——请参阅 许可证 文件以获取详细信息。

安全： 通过以下方式报告漏洞 对于这个存储库。