ads-mcp

ads-mcp

直接封装 Google Ads API 和 Meta Marketing API 的 MCP 服务，无需第三方配额或中间商。将兼容 MCP 的客户端连接到此服务，即可通过 Google 和 Meta 自己的 API 管理 Search 广告系列、关键词、广告，以及完整的 Meta 广告系列生命周期（创建、发布、监控、报告）。

所有可能产生费用的写入工具默认都是安全的：google_ads_create_search_campaign 和所有 Meta 创建/复制工具始终会创建状态为 PAUSED 的对象。只有显式调用 google_ads_set_campaign_status 和 meta_ads_set_campaign_status / meta_ads_set_ad_set_status / meta_ads_set_ad_status 才能启用支出。

设置

凭据需要使用只有你才能提供的登录信息和企业身份；这里没有任何步骤可以自动完成。不要提交 .env。

Google Ads

1. Google Cloud 项目 + OAuth 客户端：访问 console.cloud.google.com，创建新项目（或使用现有项目），进入 APIs & Services → Credentials → Create OAuth client ID（类型：Desktop app）。将 Client ID/Secret 复制到 .env。
2. 在该 OAuth 客户端下，将 http://localhost:8787/oauth2callback 添加为授权重定向 URI。
3. Developer token：访问 ads.google.com/aw/apicenter，申请令牌。Basic access 免费，通常会在几天内获批；每天允许约 15,000 次操作。将其作为 GOOGLE_ADS_DEVELOPER_TOKEN 放入 .env。
4. 运行 pnpm install，然后运行 pnpm google:auth。这会打开浏览器，你登录并同意授权后，命令会打印一个刷新令牌，将其作为 GOOGLE_ADS_REFRESH_TOKEN 粘贴到 .env。
5. 将 GOOGLE_ADS_CUSTOMER_ID 设置为这些工具默认操作的 10 位账号 ID（不含连字符）。如果该账号由 MCC 账号管理，还要将 GOOGLE_ADS_LOGIN_CUSTOMER_ID 设置为 MCC 的 ID。

Meta Ads（System User 令牌）

当 Facebook 显示登录验证关卡时，个人用户令牌会失效（Graph 错误 190 / 子代码 459）。Business Manager System User 令牌是让 Marketing API 访问不受个人浏览器会话影响的官方支持方式。

1. Meta App：developers.facebook.com，进入 My Apps，选择 Create App（类型：Business）。从 Settings > Basic 复制 App ID 和 App Secret，并将其填入 .env，分别设为 META_APP_ID / META_APP_SECRET。
2. Business Manager：打开 business.facebook.com > Business Settings。
3. 创建 System User：Users > System Users > Add。选择 Admin 最简单，可用于分配广告账户、Page 和 pixel。名称可设为 ads-mcp 之类。
4. 为该 System User 分配资产（Add Assets）：
   • 广告账户：允许管理广告系列（或授予完全控制权限）。
   • 创意中使用的 Facebook Page：允许创建内容 / 管理广告（或授予完全控制权限）。
   • 用于优化的 Pixel：允许投放广告。
5. 生成令牌：在 System User 页面选择 Generate New Token。选择第 1 步中的应用。至少请求以下权限：
   • ads_management
   • ads_read
   • business_management
   • pages_show_list
   • pages_read_engagement
   • pages_manage_ads（创建未发布的 Page 帖子 / 关联创意时需要） 如果界面提供永不过期的令牌，请选择该选项。
6. 将令牌填入 .env，设为 META_ACCESS_TOKEN。切勿提交该令牌。
7. 将 META_AD_ACCOUNT_ID 设为数字形式的账户 ID（act_ 前缀可选）。也可设置 META_PAGE_ID 和 META_PIXEL_ID，这样调用创建工具时就无需每次都提供它们。
8. 可选：META_GRAPH_API_VERSION 用于固定 Graph 版本。默认值为 v26.0。

App Review / Development 模式。 如果应用、广告账户、Page 和 pixel 都属于同一个 Business，那么即使应用处于 Development 模式（Standard Access），System User 令牌通常也能正常使用，无需 App Review。若要管理其他企业的广告账户，或者应用处于 Live 状态且相关权限受限，则需要 Advanced Access 和 App Review。Meta 最常要求审核的权限是 ads_management 和 pages_*。

住房、就业、信贷以及（在某些地区）金融产品和服务广告必须相应设置 special_ad_categories（HOUSING、EMPLOYMENT、CREDIT、FINANCIAL_PRODUCTS_SERVICES）。这些广告系列有额外的定向限制；根据类别，可能必须使用或禁止使用 Advantage+。

请先调用 meta_ads_get_account。如果已设置 META_APP_ID 和 META_APP_SECRET，响应中会包含令牌调试信息（权限范围、过期时间）。

此服务转换的 Graph 错误

代码	常见原因	处理方法
190 / 102	令牌已过期、已撤销或无效	生成新的 System User 令牌
190 + 子代码 459，或代码 459	用户登录验证关卡	完成 Facebook 登录验证，然后切换到 System User 令牌
10、200-299	缺少权限或资产分配	分配广告账户 / Page / pixel；添加上述权限；若应用处于 Live 状态或涉及跨企业操作，则进行 App Review
100 + error_user_title / error_user_msg	字段无效或广告违反政策	修正字段或创意。无法通过 API 绕过政策拒绝
4 / 17 / 32 / 613	速率限制	等待后重试
368	临时政策限制	查看 Business Support Home 和账户的 Quality 标签页

运行

pnpm install
pnpm test
pnpm dev        # MCP server over stdio via tsx
pnpm build && pnpm start   # compiled version

发布到 npm 后，也可以通过 npx @gudlab/ads-mcp 运行，无需克隆到本地。将兼容 MCP 的客户端指向它，例如在 Claude Code 的 .mcp.json 中：

{
  "mcpServers": {
    "ads-mcp": {
      "command": "npx",
      "args": ["-y", "@gudlab/ads-mcp"],
      "env": {
        "GOOGLE_ADS_CLIENT_ID": "...",
        "GOOGLE_ADS_CLIENT_SECRET": "...",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "...",
        "GOOGLE_ADS_REFRESH_TOKEN": "...",
        "GOOGLE_ADS_CUSTOMER_ID": "...",
        "META_APP_ID": "...",
        "META_APP_SECRET": "...",
        "META_ACCESS_TOKEN": "...",
        "META_AD_ACCOUNT_ID": "...",
        "META_PAGE_ID": "...",
        "META_PIXEL_ID": "..."
      }
    }
  }
}

发布前，请改为指向本地构建：command: "node"、args: ["/path/to/ads-mcp/dist/index.js"]，或者使用 command: "pnpm"、args: ["dev"]，并将 cwd 设为此目录，以便在本地迭代。

首次实际运行：先验证，再信任

Google Ads 和 Meta Marketing API 会在不同版本间更改字段和枚举名称，因此在将此处的任何工具用于实际广告系列工作前：

1. 首先以只读方式运行 google_ads_list_campaigns / meta_ads_get_account / meta_ads_list_campaigns，这是确认身份验证和客户端库配置正确的最省事方法。
2. 使用临时名称测试 google_ads_create_search_campaign 或 meta_ads_create_campaign，然后在广告界面中检查结果，不要仅凭工具自身的响应来判断是否正确。
3. 只有完成上述步骤后，才对实际广告系列使用带有 ACTIVE 的 *_set_*_status。

Meta 端到端示例（最后一步之前始终保持暂停状态）

预算使用广告账户的货币（例如，20 表示 20 GBP，发送到 Graph 时会转换为 2000 个最小货币单位）。

1. meta_ads_get_account
     Confirm the token is valid and the account currency / timezone.

2. meta_ads_search_targeting
     { "q": "online shopping", "type": "interest" }
     Copy an interest id from the results. Some detailed interests have been retired by Meta; try a broader query or type=behavior if this is empty.

3. meta_ads_estimate_audience
     { "targeting": { "countries": ["GB"], "age_min": 25, "age_max": 54, "interests": [{ "id": "6003139266461" }] },
       "optimization_goal": "OFFSITE_CONVERSIONS" }

4. meta_ads_create_campaign
     { "name": "UK leads - paused",
       "objective": "OUTCOME_LEADS",
       "special_ad_categories": [] }
     Returns campaign_id. Status is PAUSED.

5. meta_ads_create_ad_set
     { "campaign_id": "<campaign_id>",
       "name": "GB 25-54 shopping",
       "daily_budget": 15,
       "optimization_goal": "OFFSITE_CONVERSIONS",
       "billing_event": "IMPRESSIONS",
       "custom_event_type": "COMPLETE_REGISTRATION",
       "advantage_audience": false,
       "targeting": {
         "countries": ["GB"],
         "age_min": 25,
         "age_max": 54,
         "interests": [{ "id": "6003139266461", "name": "Online shopping" }]
       } }
     Advantage+ audience is off (`targeting_automation.advantage_audience = 0`). Status is PAUSED.

6. meta_ads_upload_image
     { "url": "https://example.com/ads/hero.jpg" }
     or { "path": "/absolute/path/hero.jpg" }
     Returns hash.

7. meta_ads_create_ad_creative
     { "name": "Homepage v1",
       "link": "https://example.com/?utm_source=meta",
       "message": "Open an account from your banking app.",
       "headline": "Pay from your bank",
       "description": "No card needed.",
       "image_hash": "<hash>",
       "cta_type": "LEARN_MORE",
       "url_tags": "utm_source=meta&utm_medium=paid&utm_campaign=uk_leads" }

8. meta_ads_create_ad
     { "name": "Ad 1", "ad_set_id": "<ad_set_id>", "creative_id": "<creative_id>" }
     Status is PAUSED. Still no spend.

9. Activate spend, in this order (or campaign last):
     meta_ads_set_ad_status          { "ad_id": "<ad_id>", "status": "ACTIVE" }
     meta_ads_set_ad_set_status      { "ad_set_id": "<ad_set_id>", "status": "ACTIVE" }
     meta_ads_set_campaign_status    { "campaign_id": "<campaign_id>", "status": "ACTIVE" }

10. meta_ads_get_ad_status
      Review / rejection lives in ad_review_feedback and issues_info.

11. meta_ads_get_insights
      { "level": "campaign", "object_id": "<campaign_id>", "date_preset": "last_7d" }
      Optional: "breakdowns": ["age", "gender", "placement", "day"]
      or "since": "2026-10-01", "until": "2026-10-07"

工具参考

Google Ads（src/google-ads/tools.ts）：list_campaigns、get_campaign_structure、create_search_campaign（始终为 PAUSED）、add_keywords、set_keyword_status（暂停/启用，可逆）、remove_keywords（永久删除，需设置 confirm_delete: true）、update_bid_strategy、add_negative_keywords、set_campaign_status（唯一的启用/开始花费开关）。

Meta Ads（src/meta-ads/tools.ts），所有名称均以 meta_ads_ 为前缀：

工具	用途
get_account	广告账户 + 可选的令牌调试信息
list_campaigns / get_campaign / get_campaign_structure	广告系列及其嵌套广告组和广告
list_ad_sets / get_ad_set	包含定向、预算和 Advantage+ 标志的广告组
list_ads / get_ad / get_ad_status / list_ads_by_status	广告、创意素材、ad_review_feedback / issues_info
get_insights	账户 / 广告系列 / 广告组 / 广告指标，支持预设或自定义日期，可选细分
search_targeting	搜索兴趣、行为和地理位置的关键词
estimate_audience	投放 / 覆盖人数估算
create_campaign / update_campaign	目标、special_ad_categories、广告系列或广告组预算。创建后为 PAUSED
create_ad_set / update_ad_set	每日预算、优化、像素+事件、手动定向，默认关闭 Advantage+。创建后为 PAUSED
upload_image	本地路径或 URL → 图片哈希
create_ad_creative	公共主页、链接、主要文本、标题、描述、CTA、url_tags
create_ad / update_ad	添加创意素材或替换文案。创建后为 PAUSED
set_campaign_status / set_ad_set_status / set_ad_status	显式设置为 ACTIVE / PAUSED。唯一的花费开关
copy_campaign / copy_ad_set / copy_ad	复制对象，始终为 PAUSED

隐私与数据处理

所有凭据都保存在你自己的 .env 中（不会提交，参见 .gitignore），或保存在 MCP 客户端自己的环境配置中；凭据仅用于从你的计算机直接调用 Google 和 Meta 的 API。此服务不会向任何第三方发送数据：没有遥测、分析或中继服务。每个请求都会从你的进程直接发送到 googleads.googleapis.com 或 graph.facebook.com，并使用你自己的开发者令牌和访问令牌。

许可证

MIT，详见 LICENSE。