Amazon Ads MCP

ads-mcp 是 Amazon Ads agent 接入服务。它通过 MCP stdio 暴露工具，并调用 ads-web 的 /api/mcp/* 内部接口完成权限校验、广告分析和两步调价。

环境变量

ADS_WEB_BASE_URL="https://amazon.wabisei.shop"
MCP_API_KEY="mcp_xxx"

MCP_API_KEY 需要在 ads-web 店铺管理页创建。一个 Key 只绑定一个店铺分组。

命令

npm install
npm run typecheck
npm test
npm run build
npm start

用户配置

推荐用户通过 npx 启动已发布的 MCP 包，不需要 clone 项目或填写本机绝对路径：

{
  "mcpServers": {
    "amazon-ads": {
      "command": "npx",
      "args": ["-y", "@firemky/[email protected]"],
      "env": {
        "ADS_WEB_BASE_URL": "https://amazon.wabisei.shop",
        "MCP_API_KEY": "mcp_xxx"
      }
    }
  }
}

工具

• get_mcp_usage_guide：获取 MCP 使用说明、工具分组、推荐调用流程和安全规则。
• list_accessible_profiles：列出当前 Key 可访问的店铺。
• prepare_local_export_package：一键创建 CSV 数据包任务并短等待 ready；小包会继续下载 ZIP、解压、校验并创建 DuckDB 索引，返回 packagePath 和 indexPath；大包未 ready 时返回 exportId、进度和下一步分步操作。
• create_export_package：在 ads-web 服务端生成 Amazon Ads CSV 数据包，返回 exportId、packageId、校验和和各表行数。
• get_export_package：查询 CSV 数据包状态、过期时间、校验和、manifest 和质量信息。
• download_export_package：用 exportId 下载 ZIP 数据包并保存到本地路径，ZIP 内包含 manifest.json、schema.json、summary.json、quality_report.json 和 V1 CSV 文件。
• get_ads_performance_report：获取指定日期广告日报聚合；一次 MCP 调用返回汇总指标、Top campaign、Top 搜索词和下一步建议。
• list_all_ad_campaigns：只读获取当前 Key 绑定分组内所有店铺的广告活动；不暴露 profileId、campaignId 或 search。
• list_profile_ad_campaigns：只读获取单个店铺的广告活动；必须传 profileId，不暴露 search。
• list_ad_campaigns：只读获取广告活动列表和指标；不传 profileId 时查询当前 Key 绑定分组内所有店铺。
• list_campaign_bid_targets：只读获取指定广告活动的 keyword、target 等投放明细和指标，可选返回竞价建议。
• list_campaign_search_terms：只读获取指定广告活动的搜索词指标。
• list_all_search_terms：只读聚合获取当前 Key 绑定分组内所有店铺的搜索词指标；不暴露 profileId、campaignId 或 search。
• list_search_terms：只读聚合获取当前 Key 绑定分组内的搜索词指标，可按店铺或 campaign 缩小范围。
• apply_search_term_action：直接将单个搜索词添加为关键词或否定关键词；正向关键词必须传 bid。
• apply_search_term_actions_batch：批量执行搜索词加词或否定词操作，逐条返回成功或失败。
• create_operation_plan：把本地候选操作提交到 ads-web 创建统一操作计划；只创建，不执行。
• get_operation_plan：查询统一操作计划详情和 item 状态。
• preview_operation_plan：预览统一操作计划的可执行项、阻塞项、跳过项和风险摘要。
• apply_operation_plan：使用 planId 和 confirmText 执行统一操作计划。
• cancel_operation_plan：取消尚未执行的统一操作计划。
• compare_date_windows：基于本地 DuckDB 索引对比两个日期窗口的 spend、sales、orders、ACOS、ROAS 等指标。
• diagnose_campaign_deep_dive：基于本地 DuckDB 索引做 campaign 综合诊断，返回变更归因、campaign、竞价、预算、placement、搜索词、executableCandidates、reviewOnlyCandidates 和可直接用于 create_operation_plan 的 operationPlanDraft。
• diagnose_campaign：基于本地索引诊断 campaign 级高花费无转化、ACOS 偏高等问题。
• find_waste_search_terms：查找高花费低转化搜索词，返回否词候选 finding。
• find_growth_search_terms：查找有订单且 ACOS 可接受的增长搜索词，返回加词候选 finding。
• find_existing_keyword_coverage：检查指定搜索词是否已被精准关键词或否定词覆盖。
• find_duplicate_search_terms：查找跨 campaign 或 ad group 重复出现的搜索词。
• find_bid_issues：诊断 targeting 竞价问题和低曝光转化机会。
• find_budget_pressure：诊断 campaign 平均日花费与日预算的压力。
• find_placement_issues：诊断 placement 表现强弱和浪费来源。
• draft_operation_items：把带 suggestedAction 的 findings 转成本地候选操作；候选不可直接执行。
• get_ads_snapshot：只读获取广告分析快照；可按分组或单店铺聚合广告活动，必要时附带重点活动的投放明细。
• analyze_bid_targets：分析 campaign、keyword 或 target 表现。
• create_bid_adjustment_plan：生成竞价调整计划。
• apply_bid_adjustment_plan：使用 planId 和 confirmText 执行计划。

数据获取建议

agent 做广告分析前，建议先按以下顺序读取数据：

1. 调用 get_mcp_usage_guide 获取工具分组、推荐流程和安全规则。
2. 长期完整分析优先调用 prepare_local_export_package。若返回 ready=false，保存 exportId，继续用 get_export_package 轮询，ready 后再下载、解压、校验和建 DuckDB 索引。
3. 准备完成后，使用返回的 packagePath 读取 CSV、summary.json 和 quality_report.json，或使用返回的 indexPath 直接调用本地 SQL/诊断工具。
4. 只有需要深挖具体 campaign 时，才调用 list_campaign_bid_targets 获取投放明细。
5. 只有需要分析用户查询词时，才调用 list_campaign_search_terms 或 list_all_search_terms。
6. 需要快速摘要但不需要完整本地文件时，可调用 get_ads_performance_report。

数据获取工具都是只读工具，不会修改广告。推荐写入流程是：优先调用 diagnose_campaign_deep_dive，若返回的 operationPlanDraft.items 非空，把 profileId、expiresInMinutes、items 传给 create_operation_plan 创建计划，再调用 preview_operation_plan 复核 ready/warning/blocked。agent 应在对话里展示计划摘要、风险、before/after、原因、证据和 confirmText；用户在对话中明确确认后，才用原样 confirmText 调用 apply_operation_plan。Web 页面确认是可选管理入口，适合查看历史、取消计划和排查失败，不是唯一确认入口。reviewOnlyCandidates 只用于分析报告或人工复核，不直接提交执行。手动组合单项诊断时，可调用 draft_operation_items 生成本地候选，再进入同样的操作计划流程。旧的 apply_search_term_action 和 apply_search_term_actions_batch 仍保留为兼容工具，但会立即创建关键词或否定关键词，调用前必须确认 profileId、campaignId、adGroupId、searchTerm、匹配方式和正向关键词 bid。

搜索词加词的匹配方式对 MCP 客户端使用中文：正向关键词传 精准、词组、广泛；否定关键词传 否定精准、否定词组。MCP 内部会转换成 ads-web/Amazon Ads 需要的枚举值。

通用工具会保留少量可选参数以支持复杂筛选；常规场景应优先使用专用窄工具，减少 agent 误传 "omit"、"none"、"__NO_SEARCH__" 或 dummy 值。ads-web 后端也会把这些常见占位字符串视为未传，避免误过滤。

prepare_local_export_package 是完整本地分析的推荐入口，但不会在单次 MCP 调用里长时间阻塞等待大包完成。create_export_package、get_export_package、download_export_package 保留为分步续跑和排查工具。CSV 数据包 V1 不包含小时级数据，也不会导出 campaign_hourly.csv。get_ads_performance_report 只适合快速摘要，不替代完整本地分析。MCP 对外不再提供临时 artifactId/JSONL 大文件路线，大数据分析统一使用标准 CSV 数据包，避免字段不完整、文件过期和 agent 路径分叉。

大数据文件

CSV 数据包默认包含：

• manifest.json
• schema.json
• summary.json
• quality_report.json
• core/stores.csv
• core/profiles.csv
• core/campaigns.csv
• core/ad_groups.csv
• core/targeting.csv
• core/negative_targeting.csv
• core/product_ads.csv
• core/performance_daily.csv
• sp/search_terms.csv
• sb/search_terms.csv
• placement/placement_performance_daily.csv
• business/purchased_products.csv
• audit/change_history.csv
• memory/optimization_history.csv

本地 CSV 数据包工具

推荐流程：

1. 调用 prepare_local_export_package，传入日期范围、广告类型和 outputDir。
2. 如果返回 ready=false，使用返回的 exportId 调用 get_export_package 轮询；ready 后调用 download_export_package，解压 ZIP，再调用 validate_package 和 build_local_index。
3. 如果工具直接完成，返回 packagePath、zipPath、indexPath、校验结果和表清单。
4. 调用 run_local_sql、query_table、aggregate_metrics 做自定义分析。
5. 优先调用 diagnose_campaign_deep_dive 做 campaign 综合诊断；它会返回分区 findings、executableCandidates、reviewOnlyCandidates 和 operationPlanDraft。
6. 若 operationPlanDraft.items 非空，把 operationPlanDraft.profileId、operationPlanDraft.expiresInMinutes、operationPlanDraft.items 传给 create_operation_plan。该步骤只创建计划，不执行广告修改。
7. 调用 preview_operation_plan 复核 ready/warning/blocked 和风险摘要；agent 在对话中展示计划摘要和 confirmText，用户明确确认后，才用原样 confirmText 调用 apply_operation_plan。
8. reviewOnlyCandidates 只写入报告或展示给用户，不直接提交到 create_operation_plan。
9. 需要专项深挖时，再调用 compare_date_windows、diagnose_campaign、find_waste_search_terms、find_growth_search_terms、find_existing_keyword_coverage、find_duplicate_search_terms、find_bid_issues、find_budget_pressure、find_placement_issues；手动组合 findings 时可用 draft_operation_items 生成本地候选。

如果需要排查服务端任务、下载或解压的具体环节，可以改用分步流程：create_export_package -> get_export_package -> download_export_package -> 手动解压 -> open_local_package -> validate_package -> build_local_index。

本地工具只读取本地 CSV/JSON 或 build_local_index 生成的 DuckDB 索引，不连接 PostgreSQL，不读取 Amazon refresh token，不调用 ads-web，也不直接修改广告。

安全边界

• MCP 不直接连接数据库。
• MCP 不持有 Amazon refresh token。
• MCP 不创建广告、不删除广告、不改 campaign budget。
• 本地 CSV 数据包工具和本地诊断分析工具只读本地文件或 DuckDB index，不调用 ads-web。
• diagnose_campaign_deep_dive 返回的 operationPlanDraft 只用于创建操作计划，不能跳过 preview_operation_plan 和用户确认。
• 用户确认可以在 agent 对话中完成；Web 操作计划页面是可选管理入口，不是唯一确认入口。
• draft_operation_items 只生成本地候选，不能直接执行；真实修改必须先由 ads-web 创建操作计划，并按产品规则确认。
• 推荐通过 create_operation_plan、preview_operation_plan、apply_operation_plan 执行搜索词加词、否词、keyword/target 调价和 keyword/target 暂停。
• MCP 可按用户明确调用旧的立即执行搜索词工具，将搜索词直接创建为关键词或否定关键词；正向关键词必须显式传入竞价。
• 实际调价必须先生成计划，再用确认文本执行。