元广告 MCP

用于与 Meta 广告 API 交互的模型上下文协议 (MCP)服务器。该工具使 AI 模型能够通过标准化界面访问、分析和管理 Meta 广告活动，从而允许 LLM 检索效果数据、可视化广告创意，并为 Facebook、Instagram 和其他 Meta 平台提供战略洞察。

**免责声明：**本工具为非官方第三方工具，与 Meta 没有任何关联、认可或附属关系。本项目独立维护，并根据 Meta 的服务条款使用其公共 API。Meta、Facebook、Instagram 和其他 Meta 品牌名称均为其各自所有者的商标。

屏幕截图：使用 LLM 了解您的广告效果。

特征

• 人工智能驱动的营销活动分析：让你最喜欢的法学硕士 (LLM) 分析你的营销活动，并提供关于绩效的可操作见解
• 战略建议：获得数据支持的建议，以优化广告支出、定位和创意内容
• 自动监控：要求任何与 MCP 兼容的 LLM 跟踪性能指标并提醒您重大变化
• 预算优化：获取将预算重新分配给效果更好的广告组的建议
• 创意改进：接收有关广告文案、图像和号召性用语的反馈
• 广告系列管理：请求更改广告系列、广告组和广告（所有更改都需要明确确认）
• 跨平台集成：可与 Facebook、Instagram 和所有 Meta 广告平台配合使用
• 通用 LLM 支持：兼容任何 MCP 客户端，包括 Claude Desktop、Cursor、Cherry Studio 等
• 简单身份验证：通过安全的 OAuth 身份验证轻松设置
• 跨平台支持：适用于 Windows、macOS 和 Linux

安装

使用 uv（推荐）

使用 uv 时无需特殊安装。我们可以使用 uvx 直接运行 meta-ads-mcp：

如果你想安装该包：

对于开发（如果您已经克隆了存储库）：

使用 pip

或者，您可以通过 pip 安装 meta-ads-mcp：

安装后，您可以按以下方式运行它：

配置

使用 Pipeboard 身份验证快速入门（推荐）

配置 Meta Ads MCP 最简单的方法是使用 Pipeboard 身份验证：

1. 在Pipeboard.co注册并生成 API 令牌 -在https://pipeboard.co获取免费令牌
2. 设置环境变量：
   export PIPEBOARD_API_TOKEN=your_pipeboard_token # Token obtainable via https://pipeboard.co
3. 无需设置 Meta Developer App 即可运行 meta-ads-mcp：
   uvx meta-ads-mcp

此方法提供更长寿命的令牌（60 天）、简化的设置和自动令牌更新。

与 Cursor 或 Claude Desktop 一起使用

将其添加到您的claude_desktop_config.json以与 Claude 集成，或添加到~/.cursor/mcp.json以与 Cursor 集成：

或者如果您更喜欢直接 Meta 身份验证（使用您自己的 Facebook 应用程序）：

可用的 MCP 工具

1. mcp_meta_ads_get_ad_accounts
   • 获取用户可以访问的广告帐户
   • 输入：
     • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）
     • user_id ：当前用户的元用户 ID 或“我”
     • limit ：返回的最大帐户数（默认值：10）
   • 返回：可访问的广告帐户及其详细信息的列表
2. mcp_meta_ads_get_account_info
   • 获取有关特定广告帐户的详细信息
   • 输入：
     • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）
     • account_id ：元广告帐户 ID（格式：act_XXXXXXXXX）
   • 返回：指定账户的详细信息
3. mcp_meta_ads_get_campaigns
   • 获取 Meta Ads 帐户的广告活动（可选过滤）
   • 输入：
     • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）
     • account_id ：元广告帐户 ID（格式：act_XXXXXXXXX）
     • limit ：返回的最大广告系列数量（默认值：10）
     • status_filter ：按状态过滤（全部为空，或“ACTIVE”、“PAUSED”等）
   • 返回：符合条件的活动列表
4. mcp_meta_ads_get_campaign_details
   • 获取有关特定活动的详细信息
   • 输入：
     • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）
     • campaign_id ：元广告活动 ID
   • 返回：有关指定活动的详细信息
5. mcp_meta_ads_create_campaign
   • 在 Meta Ads 帐户中创建新广告系列
   • 输入：
     • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）
     • account_id ：元广告帐户 ID（格式：act_XXXXXXXXX）
     • name ：活动名称
     • objective ：活动目标（知名度、流量、参与度等）
     • status ：初始活动状态（默认值：已暂停）
     • special_ad_categories ：特殊广告类别列表（如果适用）
     • daily_budget ：账户货币的每日预算（以美分计）
     • lifetime_budget ：账户货币的终身预算（以美分计）
   • 返回：确认新的活动详情
6. mcp_meta_ads_get_adsets
   • 获取 Meta Ads 帐户的广告组，并可选择按广告系列进行筛选
   • 输入：
     • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）
     • account_id ：元广告帐户 ID（格式：act_XXXXXXXXX）
     • limit ：返回的广告集的最大数量（默认值：10）
     • campaign_id ：可选的广告系列 ID，用于筛选
   • 返回：符合条件的广告组列表
7. mcp_meta_ads_get_adset_details
   • 获取有关特定广告集的详细信息
   • 输入：
     • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）
     • adset_id ：元广告广告组 ID
   • 返回：指定广告集的详细信息
8. mcp_meta_ads_get_ads
   • 通过可选的过滤功能获取 Meta Ads 帐户的广告
   • 输入：
     • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）
     • account_id ：元广告帐户 ID（格式：act_XXXXXXXXX）
     • limit ：返回广告的最大数量（默认值：10）
     • campaign_id ：可选的广告系列 ID，用于筛选
     • adset_id ：可选的广告组 ID，用于过滤
   • 返回：符合条件的广告列表
9. mcp_meta_ads_get_ad_details
   • 获取有关特定广告的详细信息
   • 输入：
     • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）
     • ad_id ：元广告广告 ID
   • 返回：指定广告的详细信息
10. mcp_meta_ads_get_ad_creatives

• 获取特定广告的创意详情
• 输入：
  • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）
  • ad_id ：元广告广告 ID
• 返回：创意详情，包括文本、图片和 URL

11. mcp_meta_ads_get_ad_image

• 一步获取、下载并可视化元广告图像
• 输入：
  • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）
  • ad_id ：元广告广告 ID
• 返回：可供直接视觉分析的广告图像

12. mcp_meta_ads_update_ad

• 使用新设置更新广告
• 输入：
  • ad_id ：元广告广告 ID
  • status ：更新广告状态（ACTIVE、PAUSED 等）
  • bid_amount ：以账户货币表示的出价金额（以美元美分表示）
  • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）
• 返回：带有更新的广告详情和确认链接的确认

13. mcp_meta_ads_update_adset

• 使用包括频次上限在内的新设置更新广告组
• 输入：
  • adset_id ：元广告广告组 ID
  • frequency_control_specs ：频率控制规范列表
  • bid_strategy ：出价策略（例如“LOWEST_COST_WITH_BID_CAP”）
  • bid_amount ：以账户货币表示的出价金额（以美元美分表示）
  • status ：更新广告组状态（ACTIVE、PAUSED 等）
  • targeting ：定位规范，包括定位自动化
  • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）
• 返回：带有更新的广告组详细信息和确认链接的确认

14. mcp_meta_ads_get_insights

• 获取广告系列、广告组、广告或帐户的效果洞察
• 输入：
  • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）
  • object_id ：广告系列、广告组、广告或帐户的 ID
  • time_range ：洞察的时间范围（默认值：最大值）
  • breakdown ：可选细分维度（例如年龄、性别、国家）
  • level ：聚合级别（广告、广告组、广告系列、帐户）
• 返回：指定对象的性能指标

15. mcp_meta_ads_debug_image_download

• 调试图像下载问题并报告详细诊断
• 输入：
  • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）
  • url ：直接测试图像 URL（可选）
  • ad_id ：Meta Ads 广告 ID（可选，未提供 url 时使用）
• 返回：有关图像下载尝试的诊断信息

16. mcp_meta_ads_get_login_link

• 获取可点击的 Meta Ads 身份验证登录链接
• 注意：此方法仅适用于您使用自己的 Facebook 应用的情况。如果使用 Pipeboard 身份验证（推荐），请改为设置 PIPEBOARD_API_TOKEN 环境变量（令牌可通过https://pipeboard.co获取）。
• 输入：
  • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）
• 返回：用于 Meta 认证的可点击资源链接

创建 Meta 开发者应用程序

在使用 MCP 服务器之前，您需要设置一个 Meta 开发者应用程序：

1. 前往Meta for Developers并创建一个新应用
2. 选择“消费者”应用类型
3. 在您的应用设置中，添加“营销 API”产品
4. 配置应用的 OAuth 重定向 URI 以包含http://localhost:8888/callback
5. 记下您的应用程序 ID（客户端 ID），以便与 MCP 一起使用

验证

Meta Ads MCP 支持两种身份验证方法：

1. Pipeboard 身份验证（推荐⭐）

此方法使用Pipeboard.co来管理 Meta API 身份验证，提供更长寿命的令牌和简化的流程：

1. 获取您的 Pipeboard 令牌：在https://pipeboard.co注册以生成您的免费 API 令牌
2. 使用您的令牌设置PIPEBOARD_API_TOKEN环境变量：
   export PIPEBOARD_API_TOKEN=your_pipeboard_token
3. 正常运行 Meta Ads MCP - 它将自动检测并使用 Pipeboard 身份验证：
   uvx meta-ads-mcp
4. 第一次运行命令时，您将获得一个登录 URL 以使用 Meta 进行授权

Pipeboard 认证的优点：

• ✅ 更长寿命的令牌（60 天）
• ✅ 无需配置 Meta Developer App
• ✅ 只需一个 API 令牌即可进行更简单的设置
• ✅ 自动令牌更新

要测试 Pipeboard 身份验证流程：

2. 直接 Meta OAuth（旧版）

这是为桌面应用设计的传统 OAuth 2.0 流程。仅当您使用自己的 Facebook 应用而非 Pipeboard 时才应使用此方法。

进行身份验证时，它将：

1. 在您的机器上启动本地回调服务器
2. 打开浏览器窗口以使用 Meta 进行身份验证
3. 要求您授权该应用
4. 重定向回本地服务器以安全地提取和存储令牌

此方法需要您首先创建一个 Meta Developer App 。

故障排除和日志记录

Meta Ads MCP 包含一个全面的日志系统，可帮助解决问题：

日志位置

日志文件存储在特定于平台的位置：

• macOS ： ~/Library/Application Support/meta-ads-mcp/meta_ads_debug.log
• Windows ： %APPDATA%\meta-ads-mcp\meta_ads_debug.log
• Linux ： ~/.config/meta-ads-mcp/meta_ads_debug.log

常见问题

身份验证问题

如果您遇到身份验证问题：

1. 推荐：使用 Pipeboard 身份验证
   • 设置export PIPEBOARD_API_TOKEN=your_token并重试
   • 这提供了更长寿命的令牌和更好的可靠性
   • 在 Pipeboard 仪表板中验证您的令牌
2. 对于应用程序 ID 问题（使用直接身份验证时）：如果遇到类似(#200) Provide valid app ID错误，请检查以下内容：
   • 确保你已正确设置 Meta Developer App
   • 使用以下方法之一验证您传递的 App ID 是否正确：
     • 设置META_APP_ID环境变量： export META_APP_ID=your_app_id
     • 将其作为命令行参数传递： meta-ads-mcp --app-id your_app_id

API 错误

如果您收到来自 Meta API 的错误：

1. 验证您的应用是否已添加营销 API 产品
2. 确保用户对广告帐户拥有适当的权限
3. 检查您的应用是否有速率限制或其他限制

调试命令

对于特定的图像下载问题，请使用内置诊断工具：

这将为您提供有关下载过程和潜在问题的详细信息。

使用不同的 App ID 运行

如果您需要将不同的 Meta App ID 用于不同的目的：

隐私和安全

Meta Ads MCP 遵循安全最佳实践：

1. 令牌缓存在特定于平台的安全位置：
   • Windows： %APPDATA%\meta-ads-mcp\token_cache.json或%APPDATA%\meta-ads-mcp\pipeboard_token_cache.json
   • macOS： ~/Library/Application Support/meta-ads-mcp/token_cache.json或~/Library/Application Support/meta-ads-mcp/pipeboard_token_cache.json
   • Linux： ~/.config/meta-ads-mcp/token_cache.json或~/.config/meta-ads-mcp/pipeboard_token_cache.json
2. 您不需要为每个命令提供访问令牌；它将自动从缓存中检索。
3. 您可以设置以下环境变量，而不是将它们作为参数传递：
   • META_APP_ID ：您的 Meta App ID（客户端 ID）- 用于直接 OAuth 方法
   • PIPEBOARD_API_TOKEN ：您的 Pipeboard API 令牌 - 用于 Pipeboard 身份验证方法

测试

CLI 测试

运行测试脚本来验证身份验证和基本功能：

使用--force-login标志强制进行新的身份验证，即使存在缓存的令牌：

LLM接口测试

当使用带有 LLM 接口的 Meta Ads MCP（如 Claude）时：

1. 如果使用直接 Meta 身份验证（您自己的 Facebook 应用），请通过调用mcp_meta_ads_get_login_link工具来测试身份验证
2. 如果使用 Pipeboard 身份验证（推荐），请确保设置了 PIPEBOARD_API_TOKEN 环境变量（可通过https://pipeboard.co获取令牌）
3. 通过调用mcp_meta_ads_get_ad_accounts验证帐户访问权限
4. 使用mcp_meta_ads_get_account_info检查特定帐户的详细信息

如果需要，这些功能将自动处理身份验证，并在需要时提供可点击的登录链接。

故障排除

身份验证问题

如果您遇到身份验证问题：

1. 使用LLM接口时：
   • 如果使用直接 Meta 身份验证（您自己的 Facebook 应用），请使用mcp_meta_ads_get_login_link工具生成新的身份验证链接
   • 如果使用 Pipeboard 身份验证（推荐），请确保设置了 PIPEBOARD_API_TOKEN 环境变量（可通过https://pipeboard.co获取令牌）
   • 确保您点击链接并在浏览器中完成授权流程
   • 检查回调服务器是否正常运行（该工具将报告此情况）
2. 使用 Pipeboard 身份验证时：
   • 验证您的PIPEBOARD_API_TOKEN是否设置正确（可通过https://pipeboard.co获取令牌）
   • 通过访问提供的登录 URL 检查是否需要完成授权过程
   • 尝试强制新登录： python test_pipeboard_auth.py --force-login
3. 使用直接 Meta OAuth 时：
   • 使用--force-login运行以获取新令牌： uvx meta-ads-mcp --login --app-id YOUR_APP_ID --force-login
   • 确保终端具有打开浏览器窗口的权限

API 错误

如果您收到来自 Meta API 的错误：

1. 验证您的应用是否已添加营销 API 产品
2. 确保用户对广告帐户拥有适当的权限
3. 检查您的应用是否有速率限制或其他限制

版本控制

您可以检查包的当前版本：