Meta Ads Mcp Scaleforge

ScaleForge 的 Meta Ads MCP

通过 Claude、ChatGPT、Cursor 或任何兼容 MCP 的 Agent 控制 Facebook 和 Instagram 广告。

直接封装 Meta Graph API v24.0。提供 32 个工具。无需后端，只需准备自己的 Meta 访问令牌。

---

问题

Meta 的 Marketing API 功能强大，但使用起来令人头疼。任何尝试自动化 Meta Ads 的人都会遇到以下五个难题：

1. 速率限制打地鼠（错误代码 #17）。 脚本在一次推广活动进行到一半时遇到 User request limit reached，导致广告系列处于半配置状态。Meta 每个账户的调用额度每 5 分钟重置一次，但 API 不会在缺乏上下文的情况下告诉你这一点。
2. 令牌过期乱象。 Graph API Explorer 中的用户访问令牌每隔约 2 小时就会失效。你修复一个 Bug，午餐回来后，每个请求突然都变成了 (#190) Error validating access token。
3. 从 v22 迁移到 v24 时的弃用项（2025 年 9 月）。 instagram_actor_id → instagram_user_id，degrees_of_freedom_spec 已完全移除，asset_feed_id 自 v3.1 起已弃用。从 Stack Overflow 复制粘贴的示例代码会悄无声息地失效。
4. 图片哈希按广告账户区分。 在账户 A 上传的图片无法用于账户 B——在第二个账户上会收到 Image Not Found。视频 ID 是全局通用的，但图片哈希不是。这会让 100% 首次尝试多账户自动化的人踩坑。
5. 每个主页最多投放 250 条广告。 Meta 按主页（而非账户）限制正在投放或审核中的广告数量，而且所有使用该主页的账户共用此限额。超出限额后，第 251 条广告会在审核中悄无声息地失败。

解决方案

此 MCP 是对 Meta Graph API 的轻量级类型化封装，已解决上述五个痛点：

• 批量操作自动分批（pause_campaigns_batch、activate_campaigns_batch、update_bids_batch）——每个 HTTP 请求最多处理 50 个操作，并自动分块。批量操作时可避开速率限制错误代码 #17。
• 每次批量启用前进行 ads_volume 预检——在 Meta 悄无声息地导致审核失败之前，按广告账户提醒你主页是否接近 250 条广告的上限。
• 附带可操作链接的增强错误消息——令牌过期或触发速率限制时，MCP 会准确告知你的 Agent 应该怎么做（创建 System User 令牌、等待 5 分钟等）。
• 全面使用 v24.0——采用当前字段名称，不使用已弃用的规范结构。
• 自动配置 PBIA（get_pbia）——如果主页未关联 Instagram 账户，MCP 会按需创建由主页支持的 Instagram 账户，以便使用 IG 广告版位。

整个链路中没有 ScaleForge 后端。你的 Agent → 此 MCP → https://graph.facebook.com/v24.0/*。仅此而已。

---

托管端点（无需安装）

使用 ScaleForge 托管的 Streamable HTTP 端点——无需安装，也无需在本地运行任何内容：

• Smithery 列表： https://smithery.ai/server/kirichyk-misha/meta-ads（一键安装到 Claude Desktop、Cursor、Windsurf、Continue、ChatGPT Desktop——Smithery 会提示你输入 Meta 令牌并写入配置）。
• 直接 URL（用于自定义客户端）：https://getscaleforge.com/mcp（MCP Streamable HTTP）。通过 Smithery 会话配置或 Authorization: Bearer <token> 请求头提供令牌。

更倾向于本地 npm 安装？请使用下方的 stdio 包。

---

快速开始——任选一种

Smithery（最简单，可自动配置客户端）

npx -y @smithery/cli install @getscaleforge/mcp-meta-ads --client claude
# also: --client cursor | --client windsurf | --client continue

Smithery 会提示你输入 Meta 访问令牌并写入配置文件。

Claude Code CLI

claude mcp add scaleforge \
  --env META_ACCESS_TOKEN=YOUR_TOKEN \
  -- npx -y @getscaleforge/mcp-meta-ads

使用 claude mcp list 验证。

Claude Desktop（手动配置 JSON）

在 macOS 上编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（或 Windows / Linux 上的对应文件——如果该文件不存在，Claude Desktop 会自动创建）：

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "@getscaleforge/mcp-meta-ads"],
      "env": {
        "META_ACCESS_TOKEN": "YOUR_TOKEN_HERE"
      }
    }
  }
}

重启 Claude Desktop。32 个工具会显示在锤子图标下。

Cursor

在项目中（或全局的 ~/.cursor/mcp.json）创建 .cursor/mcp.json：

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "@getscaleforge/mcp-meta-ads"],
      "env": { "META_ACCESS_TOKEN": "YOUR_TOKEN_HERE" }
    }
  }
}

本地测试（无需配置客户端）

META_ACCESS_TOKEN=YOUR_TOKEN npx -y @getscaleforge/mcp-meta-ads

服务会通过 stdio 启动。使用 @modelcontextprotocol/inspector 进行交互式测试：

npx -y @modelcontextprotocol/inspector \
  env META_ACCESS_TOKEN=YOUR_TOKEN npx -y @getscaleforge/mcp-meta-ads

---

架构

┌──────────────┐       MCP stdio        ┌───────────────────┐    HTTPS + OAuth token    ┌──────────────────────┐
│ Claude / GPT │ ◄────────────────────► │  mcp-meta-ads     │ ◄───────────────────────► │  Meta Graph API v24  │
│   Cursor     │   JSON-RPC over stdio  │  (this package)   │   graph.facebook.com      │  Marketing API       │
│ ChatGPT Desk │                        │                   │                           │                      │
└──────────────┘                        └───────────────────┘                           └──────────────────────┘

MCP 是一个精简的类型化翻译层。它不会缓存、代理或回传数据。每次调用都会从你的计算机直接发送到 Meta 的服务器，并使用你的令牌。

---

获取 Meta 访问令牌

你需要一个具有 ads_management、ads_read、business_management 权限的访问令牌；对于 Page 范围的操作（例如 PBIA 配置），还需要 pages_read_engagement 和 pages_manage_ads 权限。

令牌有两种类型。请根据你的使用场景选择。

选项 1 — 快速令牌（2 分钟，约 2 小时后过期）

适用于：试用 MCP、快速实验、一次性脚本。

1. 打开 Graph API Explorer。
2. 在 User or Page 下拉菜单中，选择 User Token。
3. 点击 Add a Permission 并选择：ads_management、ads_read、business_management、pages_read_engagement、pages_manage_ads。
4. 点击 Generate Access Token 并批准弹出的对话框。
5. 复制顶部的令牌。这就是你的 META_ACCESS_TOKEN。

令牌约 2 小时后过期。令牌失效后，MCP 会返回一条增强错误信息，引导你访问此处。

选项 2 — 稳定令牌（永不过期）

适用于：生产环境、定时任务，以及任何不希望每 2 小时重新进行身份验证的场景。

你可以在 Meta Business Manager 中生成 System User 令牌。System User 令牌没有过期时间，并且可以限定为特定资产（广告帐户和 Pages）。ScaleForge 和所有生产环境中的 Meta 集成都使用这种令牌。

1. 创建 Facebook 应用（如果你还没有），前往 developers.facebook.com/apps。任何应用都可以，Business 类型也可以。
2. 在 business.facebook.com 创建 Business Manager。你需要用它来管理 System User。
3. 在 Business Settings → Accounts → Ad Accounts / Pages 下，将你的广告帐户和 Pages 添加到 Business。（如果它们归另一个 Business 所有，请申请访问权限。）
4. **创建 System User：**前往 Business Settings → Users → System Users → Add → 为其命名（例如 mcp-meta-ads）→ 将角色设为 Admin。 [屏幕截图：Business Settings → Users → System Users 选项卡，显示“Add”按钮]
5. **将广告帐户分配给 System User：**点击该 System User → Add Assets → 选择 Ad Accounts → 选择你的帐户 → 开启 Manage 权限。对 Pages 重复此操作。 [屏幕截图：Add Assets 对话框，突出显示“Manage”开关]
6. **生成令牌：**点击 Generate New Token → 选择你的 Facebook 应用 → 选择权限范围：
   • ads_management
   • ads_read
   • business_management
   • pages_read_engagement
   • pages_manage_ads
   • read_insights（可选——某些洞察细分需要此权限） [屏幕截图：Generate Token 对话框，显示权限范围清单]
7. 点击 Generate 并复制令牌。该令牌永不过期。请将其存储在密钥管理器、环境变量或密码管理器中。

现在即可使用：

META_ACCESS_TOKEN=EAAB...your-token... npx -y @getscaleforge/mcp-meta-ads

如果之后撤销或重新生成令牌，旧令牌会立即失效。

---

内置痛点解决方案

Meta 痛点	此 MCP 的处理方式
批量操作中的速率限制错误代码 #17	pause_campaigns_batch、activate_campaigns_batch、update_bids_batch 使用 Meta Batch API（每个请求最多 50 个操作），并自动分块，分块之间间隔 2 秒。
每个 Page 最多 250 个广告的静默上限	get_ads_volume + 在 activate_campaigns_batch 中自动进行的预检——在 Meta 开始任何审核之前，响应中就会返回警告。
令牌过期错误	enhanceMetaError 会检测错误代码 190 / 102 / 104 / 463 / 467，并返回指向稳定令牌设置的消息。
没有 IG 登录却要使用 Instagram 版位	get_pbia 会自动创建一个 Page-Backed Instagram Account，并返回 instagram_user_id，供你的 object_story_spec 使用。
v22 弃用项	使用 instagram_user_id，不使用 degrees_of_freedom_spec 和 asset_feed_id。
图片哈希的作用域	在 upload_image + create_ad_creative 中有说明——哈希按账户划分，你必须重新上传到每个目标账户。（按账户缓存的逻辑位于 ScaleForge 的后端，之后的版本会在此处添加。）

---

工具参考

32 个工具，分为 10 个类别。

账户（3）

名称	用途
list_ad_accounts	列出令牌可访问的广告账户
get_ad_account	获取单个账户的详细信息（状态、支出上限、余额）
get_ads_volume	获取每个 Page 的投放中广告数量、上限和剩余名额（预检）

广告系列（5）

名称	用途
list_campaigns	分页列出广告系列
get_campaign	按 ID 获取单个广告系列
create_campaign	写入——创建新广告系列（默认设为 PAUSED）
update_campaign	写入——更新任何可变字段
delete_campaign	写入——硬删除

广告组（5）

名称	用途
list_adsets	按 ad_account_id 或 campaign_id 列出
get_adset	按 ID 获取单个广告组
create_adset	写入——在广告系列下创建广告组
update_adset	写入——更新定向、出价、预算和状态
delete_adset	写入——硬删除

广告（4）

名称	用途
list_ads	按 ad_account_id、adset_id 或 campaign_id 列出
get_ad	按 ID 获取单个广告（包括创意、问题和预览链接）
update_ad	写入——更新名称和状态，替换创意
delete_ad	写入——硬删除

创意（4）

名称	用途
list_creatives	列出广告账户中的所有创意
get_creative	按 ID 获取单个创意
create_ad_creative	写入——通过 object_story_spec 创建单文本创意
create_ad_creative_with_asset_feed	写入——通过 asset_feed_spec 创建动态／多文本创意

媒体（2）

名称	用途
upload_video	写入——通过远程 URL 上传视频（返回 video_id）
upload_image	写入——通过远程 URL 上传图片（返回 image_hash，作用域为账户）

成效分析（3）

名称	用途
get_campaign_insights	获取广告系列层级的指标及细分数据
get_adset_insights	获取广告组层级的指标
get_ad_insights	获取广告层级的指标（比较创意）

批量操作（3）

名称	用途
pause_campaigns_batch	写入（批量）——通过 Batch API 暂停多个广告系列
activate_campaigns_batch	写入（批量）——启用多个广告系列，并预检 ads_volume
update_bids_batch	写入（批量）——更新多个广告组的 bid_amount

Page（2）

名称	用途
list_pages	列出令牌可管理的 Facebook Page
get_pbia	获取或自动创建 Page-Backed Instagram Account

广告资料库（1）

名称	用途
search_ads_library	搜索公开的 Meta 广告资料库，用于竞争研究

---

示例提示词

连接服务后，可以在你的 Agent 中尝试这些提示词。

只读

• "列出我的 Meta 广告账户，并显示哪些账户处于活跃状态、货币和支出上限。"
• "获取广告系列 1234567890 最近 14 天的洞察数据，按版位细分——哪个版位的 CPL 最低？"
• "显示账户 act_555 的 ads_volume——有没有哪个公共主页的用量超过其限额的 85%？"
• "在 Meta 广告资料库中搜索过去一个月在美国投放的 Competitor X 广告。"
• "列出广告系列 ABCD 中的所有广告组，并显示哪些广告组的 is_dynamic_creative=true。"

写入（先确认）

写入操作会更改 Meta Ads 的实时状态——支出会立即开始或停止。行为良好的 Agent（Claude、GPT-4）会在调用这些工具前，先向你显示目标列表并询问“是否继续？”

• "暂停广告系列 111、222、333——先显示它们的名称和当前支出，然后再暂停。"
• "启用广告系列 444 和 555。先运行 ads_volume 预检；如果任何公共主页的用量超过 85%，则中止并告诉我具体是哪个。"
• "将广告组 6001 和 6002 的出价提高到 $4.50。帮我换算成美分。"
• "在 act_777 中创建一个名为 'Spring Promo Test' 的新广告系列，目标为 OUTCOME_LEADS，daily_budget 为 5000 美分，状态为 PAUSED。"

---

常见问题

如何获取 Meta 访问令牌？

请参阅上文的获取 Meta 访问令牌。有两种选择：快速获取 2 小时令牌（Graph API Explorer），或获取稳定的 System User 令牌（Business Manager，永不过期）。

为什么我的令牌总是过期？

你使用的是从 Graph API Explorer 获取的 User 访问令牌。这类令牌按设计会在约 2 小时后过期。若要用于实验以外的用途，请通过 Business Manager 生成 System User 令牌——这类令牌永不过期。查看完整步骤。

什么是 ads_volume？

Meta 限制每个 Facebook 公共主页上“正在投放或审核中”的广告数量——默认上限为 250——而且所有使用该公共主页的广告账户共享此上限。get_ads_volume 工具会显示每个公共主页还剩多少余量。activate_campaigns_batch 会在预检时自动调用该工具。

这是免费的吗？

是的。采用 MIT 许可证，npm 包免费。你仍需照常向 Meta 支付广告费用。使用此 MCP 无需 ScaleForge 账户或订阅。

这与 Pipeboard / 其他 MCP 有什么不同？

• Pipeboard / 托管式 MCP——运行在对方的服务器上，你需要把令牌发送给对方，而且对方会对你进行速率限制。少量使用时还不错，但令牌会存放在别人的机器上。
• 此 MCP——在本地运行，令牌不会离开你的设备，直接连接 Meta。共有 32 个工具（覆盖范围超过我们见过的任何其他 Meta MCP）。
• ScaleForge 托管平台（见下文）——面向需要托管式 Meta 访问、RedTrack 集成、定时自动规则和 UI 仪表板的团队提供的独立产品。此 MCP 是独立工具，不依赖该平台。

不使用 ScaleForge 可以用这个吗？

可以。此 MCP 是独立的 npm 包，可直接连接 graph.facebook.com。无需任何账户。

我可以贡献更多工具吗？

欢迎贡献。请在 github.com/Mike25app/scaleforge-mcp-meta-ads 提交 PR。每个工具都是 src/tools/ 中的一个小文件——复制现有文件之一作为模板即可。

---

由 ScaleForge 提供支持

由 ScaleForge 团队构建和维护。如果你需要托管式 Meta 访问（System User 配置、RedTrack 集成、定时自动规则、仪表板），欢迎了解完整平台——无论如何，此 MCP 都会保持免费且独立。

---

安全

• 生成遵循最小权限原则的令牌。 将系统用户的权限范围限制为它所需的广告账户和公共主页。撤销令牌会立即生效。
• 切勿将令牌提交到源代码管理中。MCP 从 META_ACCESS_TOKEN 环境变量读取令牌——请将其保存在 Agent 主机的密钥存储中（例如 Claude Desktop 的 env 区块、权限设为 600 的 shell 配置文件、1Password 等）。
• 定期轮换。 即使系统用户令牌不会过期，也应按照团队政策进行轮换。在 Business Manager 中重新生成令牌会使旧令牌失效。
• 不收集遥测数据。 此 MCP 不会向外发送数据。它发出的唯一外部请求是访问 https://graph.facebook.com/v24.0/*。
• 速率限制按令牌／广告账户分别适用（由 Meta 端执行）。批量工具会自动使用 Meta Batch API，以避免超出限制。

---

链接

• npm： @getscaleforge/mcp-meta-ads
• GitHub： Mike25app/scaleforge-mcp-meta-ads
• 问题反馈： github.com/Mike25app/scaleforge-mcp-meta-ads/issues
• ScaleForge（托管平台）： getscaleforge.com
• Meta Marketing API 文档： developers.facebook.com/docs/marketing-apis

---

许可证

MIT — 请参阅 LICENSE。