amazon_ads_mcp

目录

• 它在 Kuudo 中的定位
• 什么是 MCP 工具？
• 什么是 Amazon Ads API MCP SDK？
• 快速开始
• 安装
• 配置（身份验证、软件包、配置文件、区域）
• 下载报告和导出文件
• MCP 客户端示例（Claude Desktop）
• 上下文限制
• 代码模式
• 工具审计
• 后台任务
• 常见问题
• 故障排除
• 文档导航

它在 Kuudo 中的定位

本仓库是更广泛的 Amazon Agent 平台中的工具层。Kuudo 为 Amazon Agent 提供工具、知识、工作流和工作空间。本仓库提供的就是工具。

层级	提供内容	位置
MCP 服务	Agent 调用的工具：这里是 Amazon Ads，以及 Selling Partner 和 Vendor Central 工具	本仓库，以及 MCP 工具参考
技能	更高层级的工作流：可复用、版本化的多步骤 Amazon 流程，由这些工具组合而成，并会在任何操作正式生效前等待人工确认	Amazon Agent Skills
Agent Atlas	知识：涵盖 Ads、Seller Central 和 Vendor Central 的索引化 Amazon 运营知识，并提供带引用的解答	Amazon Agent Atlas
Agent Flow	工作空间：你的 Amazon 数据存放在你自己的云端，因此 Agent 能根据真实数据作答，而不是猜测	Amazon Agent Flow

请将本仓库视为该平台的一个层级，而不是平台的全部。下方列出的操作是 Agent 可以调用的工具；技能则是 Agent 执行的工作流。

什么是 MCP 工具？

可以把 MCP（Model Context Protocol）看作 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 应用集成
• 🌍 多区域支持：提供 NA、EU 和 FE 区域端点，并支持自动路由
• 📊 全面的 API 覆盖：涵盖广告活动、档案、报告、DSP、AMC 工作流等
• 📝 类型安全：全面支持 Pydantic 模型，并提供丰富的类型提示
• 🧪 可用于生产环境：包含测试、验证和错误处理

🎯 使用场景

Claude Desktop 集成

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

AI 应用

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

企业服务

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

开发者工具

• API 封装器：针对特定使用场景创建自定义 SDK
• 测试框架：自动测试 Amazon Ads 集成
• 开发工具：本地开发和调试实用工具

为什么这个 Ads MCP 与众不同

其他 Amazon Ads MCP 只能处理顺利的常见流程。一旦 Agent 犯了个合理的错误，它们就会崩溃；而 Amazon Ads API 中这类合理的错误，比几乎任何其他大型 API 都多。v1 报告目录使用的术语与 v3 不同。文档散落在不同代际的迁移指南中。同一个字段，根据 Agent 或人类参考的教程不同，可能有三个看起来都合理的名称。

你一定遇到过这些情况

即使你从未把它们看作同一个问题，也一定熟悉这些症状：

• 正要有所进展时，突然出现“正在压缩对话……”
• 任务进行到一半时出现“已达到使用上限”，却没有任何成果，令牌全白费
• 出现“超出上下文窗口”，只能从头开始，重新解释一切
• Agent 悄悄忘了它在三轮对话前找到的解决办法
• 调用了五次工具，其中四次是在重试，却毫无进展
• 第三次把同一个错误重新粘贴到聊天中

这不是模型太笨，而是 API 接口消耗了上下文。模糊的错误会引发反复尝试，反复尝试会填满上下文窗口，窗口满了之后，有用的信息就会被挤出去。Agent 可能要来回尝试 4 到 12 次：字段名称错误、请求体结构错误、筛选运算符错误、日期位置错误、广告主账户格式错误。

在这里，错误的操作会引导出正确的操作

这个服务基于一个不同的前提构建：错误反馈面就是文档面。 每次失败都是一次学习机会，而这个服务经过专门设计，能让同一个 Agent 或下一个 Agent 在下一次尝试时做得更好，无需重新训练、更新提示词或使用记忆技巧。

• 服务会告诉你哪里出了问题，以及为什么会出错
• 每次失败都会转化为纠正措施——模型只需读取提示并继续
• 原本需要调用工具五次的调试过程，会缩短为两次调用即可完成纠正
• 一周后再犯同样的错误，也不必重新消耗上下文，因为验证器、别名表和弃用结构表仍在那里
• 不会有脱离上下文、容易遗忘的非正式经验知识

每次失败的代价都会比上一次更低。每个 Agent 都能从同一个权威来源中学习。每次重试都有明确方向。这种持续积累，才是智能 Agent 解决方案在实践中的样子。

边缘情况无处不在，你可以提供帮助

我们无法捕获所有边缘情况。Amazon 的 API 涵盖范围极其庞大，迁移历史也错综复杂，而现实中的失败情况往往比任何人能预想到的都更加多样。我们承诺采取的策略是：让错误具有指导作用，让文档出现在 Agent 实际接触的界面中，让每一次错误操作都能让下一次操作更轻松。

如果你遇到的问题是错误信息未能提供帮助——提示含糊、建议错误，或者完全没有提示——这正是我们想要的反馈。请提交 issue，粘贴错误信息，并告诉我们你原本期待什么。 这项策略的效果取决于它覆盖的情况。

快速开始

前提条件： Docker（推荐）；如果从源代码运行，则需要 Python 3.10+；还需要 Amazon Ads API 访问权限（使用你自己的开发者应用，或 Openbridge 之类的合作伙伴）。

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:<PORT>/mcp/——.env.example 中设置了 PORT=9080（如有需要，可在 .env 中覆盖）。

OAuth 步骤、客户端 JSON 示例和完整的变量参考：请参见下方的配置、INSTALL.md 和 AGENTS.md。

📚 Amazon Ads MCP 包含什么？

MCP 服务广泛覆盖 Amazon Ads API。每个启用的软件包都对应一组 API 操作，包括 Campaign Management（Amazon Ads API v1）、Exports、Amazon Marketing Cloud 等。

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

• 账户
• 受众
• 报告
• 品牌指标
• Sponsored Products
• Sponsored Brands
• Sponsored Display
• Amazon DSP
• Amazon Attribution
• 推荐与洞察
• 创意素材
• 变更历史
• 数据提供方
• 产品
• 统一预审核
• 审核
• Amazon Marketing Stream
• 地点
• 导出
• 媒体规划
• Amazon Ads API v1

🧪 Amazon Ads API v1

Amazon Ads API v1 采用全新方式重新构想 Amazon Ads API，从头构建，旨在通过通用模型为所有 Amazon 广告产品提供无缝体验。该通用模型的一项主要优势是提升了与代码生成工具（例如客户端库生成器）的兼容性。

⚠️ Beta 版公告：这些 API 目前处于 Amazon 的 Beta 阶段。功能和端点可能会发生变化。请谨慎用于生产环境。

Package Name	描述	Prefix
ads-api-v1-all	Ads API v1 合并的完整接口	allv1_
ads-api-v1-sp	Sponsored Products v1	spv1_
ads-api-v1-sb	Sponsored Brands v1	sbv1_
ads-api-v1-dsp	Amazon DSP v1	dspv1_
ads-api-v1-sd	Sponsored Display v1	sdv1_
ads-api-v1-st	Sponsored Television v1	stv1_
ads-api-v1-beta	Ads API v1 合并的 Beta 接口	beta_

要启用 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"

更多信息请参阅 Amazon 的广告活动管理概览。

不止是 MCP 服务

以上内容都是工具层：Agent 可以调用的 Amazon Ads 操作。Kuudo 在此基础上增加了三个层级，而只比较操作数量会忽略这些层级。

能力	单独的 MCP 服务	Kuudo
暴露 Amazon Ads API 操作	是	是
更高层级的多步骤工作流	否	是，通过 Skills 提供
可复用、带版本的工作流	否	是，每个 Skill 都带有版本
上线前由人工审批	否	是，激活须经审批
分叉工作流并为自己的账户修改	否	是，Skills 采用开放的纯文本格式
带引用的索引式 Amazon 知识问答	否	是，通过 Agent Atlas 提供
将自己的账户数据载入自己的云端	否	是，通过 Agent Flow 提供
跨多个 MCP 服务运行的工作流	否	是，可将 Ads 与 Selling Partner 和 Vendor Central 结合
从任意 MCP 客户端运行	不定	是，支持 Claude、ChatGPT、Cursor 等

Kuudo 通过 Skills 在 MCP 工具层之上提供更高层级的工作流。 Skill 会将这些操作组合成可重复执行的 Amazon 流程，通过 Atlas 提供依据，并在做出任何更改前等待人工审批。

安装

我们建议使用 🐳 Docker 运行 Amazon Ads API MCP。请从此代码库构建镜像（此处不支持从第三方镜像仓库使用 docker pull，请使用代码库中的 Dockerfile 和 docker-compose.yaml）。

对于 pip、自行检出源码、自定义 virtualenv、非 Docker 部署或 Code Mode 额外处理等定制安装方式，请参阅安装指南。README 保持 Docker 快速安装路径简短；INSTALL.md 则包含完整的安装方式和验证步骤。

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

复制环境模板：

cp .env.example .env

使用你的设置编辑 .env（如果更改默认值，也请设置 PORT）。

使用 Docker Compose 启动服务（根据 docker-compose.yaml 构建并标记为 amazon-ads-mcp:latest）：

docker compose up -d

服务会监听 .env 中由 PORT 映射到主机的端口（.env.example 使用 9080）。

查看日志：

docker compose logs -f

停止服务：

docker compose down

有关验证、升级、开发环境设置和非 Docker 安装方式，请参阅安装指南。

配置

**运营者／自托管用户：**请按照以下步骤和 .env 文件进行操作。聊天用户在连接服务器后，主要通过提示词进行交互；请浏览广告主资料和地区，了解资料和地区的行为。

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. 使用 OpenBridge 管理的授权
3. 使用 Kuudo 管理的授权

自带 Amazon Ads API 应用

如果您已有自己的 Amazon Ads API 应用，或想创建一个，具体流程如下。

1. 在 Amazon 注册您的应用程序

1. 前往 Amazon 开发者控制台
2. 创建或选择您的 Login with Amazon 应用程序
3. 记下您的 Client ID 和 Client Secret
4. 将回调 URL 设置为“允许的返回 URL”。该 URL 必须与此 MCP 服务 HTTP 监听器的主机和端口一致（请参阅 .env 中的 PORT；.env.example 使用 9080）：
   • 生产环境：https://your-server.com/auth/callback
   • 本地开发环境：http://localhost:<PORT>/auth/callback（例如：http://localhost:9080/auth/callback）

应用通过 Amazon 的安全审核和批准后，您需要获取客户端 ID 和密钥：

# Amazon Ads API Credentials (required)
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”

步骤 1：启动 OAuth

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

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

步骤 2：重定向到 Amazon Ads

在此示例中，系统会提示您点击链接，在浏览器窗口中打开 Amazon 并请求授权。

步骤 3：批准请求

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

步骤 4：成功

如果一切顺利，您会看到成功响应。您可以关闭浏览器窗口并返回客户端。如果看到其他内容，请重新尝试，并确认所有配置项均正确。

步骤 5：确认

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

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

现在可以开始与 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 中。你需要先在客户端请求当前身份：“"List my remote identities"”。接下来，告诉 MCP 服务使用其中一个身份：“"Set my remote identity to <>"”。然后，你可以要求 MCP 列出与该账户关联的所有 Amazon Ad 配置文件：List all of my Amazon Ad profiles。如果没有看到某个广告主，请设置其他身份。

Kuudo 合作伙伴应用

Kuudo 可从组织管理的 Amazon 连接中签发短期 Amazon Ads 凭证。使用 Kuudo M2M API 密钥配置服务器：

AUTH_METHOD=kuudo
KUUDO_API_BASE_URL=https://amazon-spapi-dev.kuudo.ai/
KUUDO_API_KEY=sk_xxxxxx
KUUDO_PROVIDER=amazon_ads

API 密钥需要 amazon-connections:read 和 amazon-tokens:vend 作用域。设置 KUUDO_REMOTE_IDENTITY_ID 可在启动时选择默认连接；也可以在调用 Amazon Ads 操作之前，使用身份工具列出并选择连接。

公开的 HTTP 部署还必须为 MCP 调用方配置 MCP_INBOUND_TOKEN 或受信任代理 HMAC 身份验证。

设置 Amazon Ads 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 (Beta)
• ads-api-v1-sb (Beta)
• ads-api-v1-dsp (Beta)
• ads-api-v1-sd (Beta)
• ads-api-v1-st (Beta)
• ads-api-v1-all
• ads-api-v1-beta (Beta)

你会注意到，有些软件包被拆分成了更小的组。例如，Amazon Marketing Cloud 分为多个套件：amc-ad-audience、amc-administration、amc-rule-audience 和 amc-workflow。这样做是为了提高效率和优化效果，降低许多 AI 客户端的上下文限制。

了解 Amazon Ads MCP 工具

Amazon Ads MCP 工具使用前缀（如 Campaign Management 的 cm_ 或 Amazon Marketing Cloud 的 amc_）来帮助整理具体的 Ads API 操作。

前缀示例：

• cm_ → 广告系列／广告 API
• amc_ → AMC 相关 API
• dsp_ → DSP API
• sd_ → Sponsored Display
• ams_ → Amazon Marketing Stream
• spv1_ → Sponsored Products v1 (Beta)
• sbv1_ → Sponsored Brands v1 (Beta)
• dspv1_ → Amazon DSP v1 (Beta)
• sdv1_ → Sponsored Display v1 (Beta)
• stv1_ → Sponsored Television v1 (Beta)

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

Campaign Management（cm_）

• cm_QueryCampaign — 查询广告系列
• cm_CreateCampaign — 创建广告系列
• cm_UpdateCampaign — 更新广告系列
• cm_DeleteCampaign — 删除广告系列
• cm_QueryAdGroup — 查询广告组

Sponsored Products（sp_）

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

AMC 工作流（amc_）

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

用户会看到如下工具：

• “列出我的 Amazon Ads 广告系列”
  → Claude 使用：cm_QueryCampaign

• “创建 AMC 工作流”
  → Claude 使用诸如 amc_executeWorkflow 的工具（发现后；具体名称取决于已启用的软件包）

• “导出我的 Sponsored Products 广告数据” → Claude 使用：export_createAdExport

📥 下载报告和导出文件

工具从 Amazon 获取报告或导出文件时，会将文件下载到运行 MCP 服务的机器上（服务主机上的本地磁盘——Docker 卷、VM 或裸机；除非服务运行在你的笔记本电脑上，否则不会下载到你的笔记本电脑）。默认基础目录为 ./data（可通过 AMAZON_ADS_DOWNLOAD_DIR 覆盖）。文件按 data/profiles/{profile_id}/… 目录结构存放。

MCP 工具会列出这些服务端文件并生成 URL；随后客户端通过 HTTP 获取文件内容（GET /downloads、GET /downloads/{relative-path}）。在这些流程中，数据不会绕过服务端存储，直接从 Amazon 流式传输到 MCP 客户端。

下载时请使用 HTTP 传输：使用 --transport http 运行（或通过 Docker 在端口 9080 上运行）。stdio 模式不会注册 /downloads，而且 get_download_url 工具在没有 HTTP 的情况下会返回错误。

报告与导出文件

• V3 异步报告： 使用 OpenAPI 工具 createAsyncReport（POST）创建报告，使用 getAsyncReport（GET）轮询状态，然后使用 download_export 将已完成的文件保存到服务端的用户档案存储中。
• 导出文件（例如广告导出文件）： 使用 OpenAPI 工具（例如 export_CampaignExport）创建任务，通过 export_GetExport 轮询，然后使用完成 URL 调用 download_export，将文件从 Amazon 获取并写入服务端（存储目录结构与报告相同）。

工作流

1. 设置活动配置文件（set_active_profile），以便限定存储和 HTTP 访问范围。
2. 创建任务： 使用相应的 OpenAPI 工具创建报告或导出文件。
3. 轮询完成状态： 使用对应的 GET 工具检查状态，直到变为 COMPLETED。
4. 下载： 使用已完成响应中的下载 URL 调用 download_export。
5. 查找或获取链接： 使用 MCP 工具 list_downloads 和 get_download_url。
6. 获取字节数据： 对第 5 步中的 URL 发起 HTTP GET 请求（可使用浏览器、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，请先通过 MCP 在同一服务上调用 set_active_profile。如果未配置身份验证管理器，也可能接受数值型 ?profile_id= 查询参数；请参阅部署设置。

提示词示例

任务	提示词示例
下载报告	“生成一份 2026 年 1 月的 Sponsored Products 报告”
列出可用文件	“显示我已下载的文件”
获取下载链接	“获取我们刚创建的报告的下载 URL”
按类型筛选	“列出我下载的广告活动导出文件”

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 的说法：资料在 Amazon Ads API 中发挥着关键作用，它决定了特定调用的管理范围。要访问特定市场中的广告主数据和服务，必须提供资料 ID。

你可能不知道授权允许你访问哪些资料。你可以列出授权可访问的所有广告资料：

• 工具：ac_listProfiles
• 示例提示词："列出我的广告主资料 ID"

**警告：**大型账户可能会返回非常多的资料，超出客户端的上下文限制。建议使用以下有范围限制的工具来查找：

• 工具：summarize_profiles — "汇总我的广告主资料"
• 工具：search_profiles — "查找美国名称中包含 Acme 的资料"
• 工具：page_profiles — "显示英国的前 20 个资料"
• 工具：refresh_profiles_cache — "刷新我的资料列表缓存"

响应包含资料详情：

• profileId、countryCode、currencyCode
• dailyBudget、timezone
• accountInfo（类型：seller/vendor/agency）

假设你的列表中包含资料 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 服务包含用于管理默认区域和动态切换区域的工具，无需重启服务即可在北美（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

在此示例中，我们展示如何使用 Openbridge API 密钥作为 bearer token。在 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 替换为实际值。

重要提示：Cursor 和 Claude Desktop（Windows 版）存在一个 bug：调用 npx 时不会转义 args 中的空格，导致这些值被破坏。你可以使用以下方式规避：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": {
        "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_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 Remote 文档，了解最新的设置和选项。

重启 Claude Desktop

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

⚠️ 上下文限制与已启用的 MCP 服务工具

MCP 工具的注册和使用可能会影响 AI 系统的使用限额。使用限额用于控制你在特定时间段内与 Claude 等 AI 系统交互的次数。正如 Anthropic 所说，可以把使用的信息量或数据量看作是在消耗“对话预算”。该预算决定了你可以向 AI 客户端发送多少条消息，或可以工作多久，之后需要等待限额重置。

MCP 服务工具会向模型的上下文提供标题、描述、提示和架构等元数据。这些元数据会加载到大模型的上下文窗口中，作为其短期工作记忆。

Claude 等每个客户端都有固定大小的上下文窗口。这决定了它在单次交互中可以处理的信息上限，包括用户提示词、系统指令、工具元数据以及之前的消息。

启用的工具越多，预先占用的有限空间就越多。启用许多工具时，它们合并后的架构和配置负载可能会大量占用上下文，你可能很快就会达到上下文上限。这时，你会开始看到超出聊天长度限制的错误或警告。

Amazon Ads MCP 覆盖整个 API，因此可能包含数百个工具！

• 工具越多，留给用户交互的空间就越少：启用不必要的工具会减少实际提示词或数据可用的空间。
• 从少量开始：仅启用当前任务所需的工具。之后随时可以添加更多工具。

如果遇到意料之外的长度问题，请检查当前启用的工具。移除未使用的工具有助于尽量减少上下文占用。

Code Mode

Code Mode 是一项可大幅减少工具 token 消耗的功能。它不会预先将每个工具的架构都加载到大模型的上下文中，而是用四个轻量级元工具替代完整目录。大模型会按需发现工具，并通过沙盒化的 Python 执行它们。

Token 影响

模式	上下文中的工具数	使用的 Token	上下文窗口
标准模式	55	~32,000	16.1%
代码模式	4	~470	0.2%
缩减比例			98.6%

以具有代表性的默认规模目录为例进行的说明性比较；实际工具数量和 Token 用量取决于 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 多个工具仍可完整使用。大模型只需按需发现并调用工具，无需预先加载每个架构。

激活代码模式

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

CODE_MODE=false

Docker Compose — 添加到 environment 部分：

environment:
  - CODE_MODE=false

Docker Run（将主机端口映射到容器的 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

配置选项

变量	默认值	描述
CODE_MODE	true	启用代码模式
CODE_MODE_INCLUDE_TAGS	true	在发现过程中包含标签浏览（目录较小时设为 false）
CODE_MODE_MAX_DURATION_SECS	30	每次沙盒运行的最长执行时间
CODE_MODE_MAX_MEMORY	50000000	每次沙盒运行的内存限制（50 MB）

使用代码模式

启用后，MCP 客户端（Claude Desktop、Claude Code 等）将只显示 4 个工具，而非完整目录。

浏览可用类别：

“有哪些工具类别？”

大模型会调用 tags，并看到 campaign-management、sponsored-products、programmatic-dsp、accounts、reporting 等类别。

查找特定工具：

“查找用于管理广告活动的工具”

大模型会调用 search("campaigns")，并获得匹配的工具名称及简短描述。

获取工具详情：

“显示创建广告活动所需的参数”

大模型会调用 get_schema("cm_CreateCampaign")，并获取完整的输入架构。

执行操作：

“列出我已启用的广告活动”

大模型会使用 Python 代码调用 execute：

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

工具类别

大模型调用 tags 时，会看到根据 API 前缀映射而来、易于理解的类别：

类别	前缀	描述
campaign-management	cm	创建、更新、查询和删除广告活动、广告组、广告及定向
sponsored-products	sp	商品推广定向、关键词和竞价
sponsored-brands	sb	品牌推广广告活动（v3 + v4）
sponsored-display	sd	展示型推广广告活动及定向工具
programmatic-dsp	dsp	DSP 广告主、受众、转化和衡量
amazon-marketing-cloud	amc	AMC 工作流、受众和管理
accounts	ac	个人资料、账单、预算、广告组合和管理者账户
reporting	rp	V3 报告工具
brand-insights	br	品牌基准和指标
stores	st	Stores 分析
server-management	—	个人资料、区域、OAuth 和下载工具

何时使用代码模式

适合使用代码模式的情况：

• 已启用许多工具包，且上下文空间不足
• 希望为对话和数据分析保留尽可能多的上下文空间
• MCP 客户端支持工具发现模式（Claude Desktop、Claude Code）

适合使用标准模式的情况：

• 启用的工具包较少（1-3 个）
• 需要尽可能快速地调用工具（无需发现步骤）
• 工作流会反复使用相同的少数几个工具

验证代码模式

使用 CODE_MODE=true 启动服务后，验证其是否已启用：

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

在 MCP 客户端中，你应该只看到 4 个工具：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：每次获取架构的平均令牌成本

后台任务

许多 Amazon Ads API 操作需要较长时间才能完成——报告生成、导出创建、AMC 工作流执行、受众处理和 DSP 测量研究可能需要几秒到几分钟。后台任务允许这些操作运行，而不会阻塞对话。

工作原理

后台任务默认启用。当客户端为任意工具请求后台执行时：

1. 启动：工具立即返回任务 ID
2. 跟踪：客户端按服务端建议的间隔轮询进度更新
3. 获取：任务完成后，客户端获取结果

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

内置工作流工具

这些工具用于编排多步骤工作流（下载并通过 HTTP 访问服务端文件）：

工具	用途
download_export	将已完成的导出文件或报告文件从 Amazon S3 下载到本地存储
list_downloads	列出当前配置文件已下载的所有文件
get_download_url	返回用于获取已下载文件的 HTTP URL

这些工具包含进度报告，客户端可以据此跟踪工作流的各个阶段。

配置

变量	默认值	描述
ENABLE_TASKS	true	为所有异步工具启用后台任务执行

禁用后台任务：

ENABLE_TASKS=false

Docker Compose — 添加到 environment 部分：

environment:
  - ENABLE_TASKS=false

后端

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

要在重启后持久跟踪任务，请配置 Redis 后端：

FASTMCP_DOCKET_URL=redis://localhost:6379

示例提示词

任务	示例提示词
生成报告	“生成一份 2026 年 3 月的 Sponsored Products 广告活动报告”
导出广告活动	“导出我所有已启用的广告活动”
运行 AMC 工作流	“执行我过去 30 天的受众重叠工作流”

常见问题

Kuudo 是否只公开 Amazon Ads API 操作？

不。此服务公开的是 Amazon Ads 操作本身。Kuudo Skills 将这些操作打包成更高层级的工作流：可复用、有版本控制的多步骤流程，可以组合多个 MCP 服务中的工具，通过 Agent Atlas 检索 Amazon 和账户知识，使用 Agent Flow 在你自己的云环境中进行持久化数据处理，并在任何内容正式上线前等待人工审批。Skills 可通过任意 MCP 客户端、代码或 CLI 运行。

我必须使用预先构建的 Skill 吗？

不。Agent 可以直接组合这些操作来完成一次性任务。Skills 适用于需要重复运行并希望每次都以相同方式执行的流程。选择一个 Skill，观察它的运行过程，然后为你的账户创建分支；也可以使用这些工具编写自己的 Skill：每个 Skill 都是纯文本的开放格式文件，而非专有格式。

这是完整产品吗？

不是。本仓库是 Amazon Ads 工具层。Kuudo 还运行用于 Selling Partner 和 Vendor Central 的 MCP 服务、Skills 工作流层、用于知识管理的 Agent Atlas，以及用于持久化数据工作的 Agent Flow。请参阅各部分如何协同运作。

故障排查

服务未连接？

• 确保 Docker 容器正在运行：docker compose ps
• 检查服务日志：docker compose logs -f
• 确认主机端口与 .env 中的 PORT 一致（.env.example 使用 9080；你的映射必须匹配）

身份验证错误？

• 检查你的 OpenBridge 令牌是否有效
• 确保已在环境中正确设置令牌
• 确认你拥有 Amazon Ads API 访问权限

Claude 无法识别服务？

• 更改配置后重启 Claude Desktop
• 如果 MCP 未激活，请在 Claude Desktop 中选择“Reload Page”
• 检查 JSON 语法是否有效
• 确保服务名称完全一致

文档索引

文档	用途
INSTALL.md	完整的安装、验证、升级和开发环境设置指南
AGENTS.md	环境变量、Docker、MCP 调优和贡献工作流
本 README	概览、身份验证指南、下载、客户端、代码模式
Kuudo MCP 工具参考	Kuudo 的所有 MCP 服务及其工具
Amazon Agent Skills	基于这些操作构建的工作流层

📄 许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。

安全： 请通过本仓库的 GitHub 私人安全公告报告漏洞。

Smithery 列表

请参阅 Smithery 发布指南，了解托管端点、API 密钥配置和发现前提条件。