元广告 MCP

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

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

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

快速入门

1. 注册Pipeboard以通过 Meta 进行身份验证（或者，您可以设置自己的自定义元应用程序）

2. 在pipeboard.co/api-tokens获取您的 Pipeboard 令牌

3. 将此配置添加到您的 MCP 客户端：

就这样！现在您可以在自己喜欢的 MCP 客户端中使用 Meta Ads MCP 了。

注意：如果您更喜欢使用自己的 Meta Developer App 而不是 Pipeboard 身份验证，请参阅CUSTOM_META_APP.md了解说明。

特征

• 人工智能驱动的营销活动分析：让你最喜欢的法学硕士 (LLM) 分析你的营销活动，并提供关于绩效的可操作见解

• 战略建议：获得数据支持的建议，以优化广告支出、定位和创意内容

• 自动监控：要求任何与 MCP 兼容的 LLM 跟踪性能指标并提醒您重大变化

• 预算优化：获取将预算重新分配给效果更好的广告组的建议

• 创意改进：接收有关广告文案、图像和号召性用语的反馈

• 广告系列管理：请求更改广告系列、广告组和广告（所有更改都需要明确确认）

• 跨平台集成：可与 Facebook、Instagram 和所有 Meta 广告平台配合使用

• 通用 LLM 支持：兼容任何 MCP 客户端，包括 Claude Desktop、Cursor、Cherry Studio 等

• 简单身份验证：通过安全的 OAuth 身份验证轻松设置

• 跨平台支持：适用于 Windows、macOS 和 Linux

高级设置

开发安装

如果您对该项目做出贡献或需要直接运行它：

隐私和安全

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

1. 令牌缓存在特定于平台的安全位置：

   • Windows： %APPDATA%\meta-ads-mcp\token_cache.json

   • macOS： ~/Library/Application Support/meta-ads-mcp/token_cache.json

   • Linux： ~/.config/meta-ads-mcp/token_cache.json

2. 您不需要为每个命令提供访问令牌；它将自动从缓存中检索。

测试

LLM接口测试

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

1. 确保已设置 PIPEBOARD_API_TOKEN 环境变量

2. 通过调用mcp_meta_ads_get_ad_accounts验证帐户访问权限

3. 使用mcp_meta_ads_get_account_info检查特定帐户的详细信息

故障排除

身份验证问题

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

1. 验证您的 Pipeboard 设置：

   • 检查PIPEBOARD_API_TOKEN是否设置正确

   • 在 Pipeboard 仪表板中验证您的令牌

   • 尝试强制新登录： python test_pipeboard_auth.py --force-login

2. 使用LLM接口时：

   • 确保已设置 PIPEBOARD_API_TOKEN 环境变量

   • 检查回调服务器是否正常运行

API 错误

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

1. 确保用户对广告帐户拥有适当的权限

2. 检查是否存在速率限制或其他限制

3. 验证你的 Pipeboard 令牌是否已过期

日志位置

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

• 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

配置

管道板认证

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

1. 在Pipeboard.co注册并生成 API 令牌

2. 设置环境变量：

   export PIPEBOARD_API_TOKEN=your_pipeboard_token

3. 运行 meta-ads-mcp - 它将自动处理身份验证

与 Cursor 或 Claude Desktop 一起使用

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

可用的 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_account_pages

   • 获取与 Meta Ads 帐户关联的页面

   • 输入：

     • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）

     • account_id ：当前用户页面的 Meta Ads 帐户 ID（格式：act_XXXXXXXXX）或“me”

   • 返回：与帐户相关的页面列表，有助于广告创建和管理。

4. mcp_meta_ads_get_campaigns

   • 获取 Meta Ads 帐户的广告活动（可选过滤）

   • 输入：

     • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）

     • account_id ：元广告帐户 ID（格式：act_XXXXXXXXX）

     • limit ：返回的最大广告系列数量（默认值：10）

     • status_filter ：按状态过滤（全部为空，或“ACTIVE”、“PAUSED”等）

   • 返回：符合条件的活动列表

5. mcp_meta_ads_get_campaign_details

   • 获取有关特定活动的详细信息

   • 输入：

     • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）

     • campaign_id ：元广告活动 ID

   • 返回：有关指定活动的详细信息

6. 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 ：账户货币的终身预算（以美分计）

   • 返回：确认新的活动详情

7. mcp_meta_ads_get_adsets

   • 获取 Meta Ads 帐户的广告组，并可选择按广告系列进行筛选

   • 输入：

     • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）

     • account_id ：元广告帐户 ID（格式：act_XXXXXXXXX）

     • limit ：返回的广告组的最大数量（默认值：10）

     • campaign_id ：可选的广告系列 ID，用于筛选

   • 返回：符合条件的广告组列表

8. mcp_meta_ads_get_adset_details

   • 获取有关特定广告集的详细信息

   • 输入：

     • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）

     • adset_id ：元广告广告组 ID

   • 返回：指定广告集的详细信息

9. mcp_meta_ads_create_adset

   • 在 Meta Ads 帐户中创建新的广告组

   • 输入：

     • account_id ：元广告帐户 ID（格式：act_XXXXXXXXX）

     • campaign_id ：此广告组所属的 Meta Ads 广告系列 ID

     • name ：广告组名称

     • status ：初始广告组状态（默认值：PAUSED）

     • daily_budget ：以账户货币（美分）表示的每日预算，以字符串形式表示

     • lifetime_budget ：账户货币（以美分计）的终身预算，以字符串形式表示

     • targeting ：定位规范（例如年龄、位置、兴趣）

     • optimization_goal ：转化优化目标（例如“LINK_CLICKS”）

     • billing_event ：您的收费方式（例如“IMPRESSIONS”）

     • bid_amount ：账户货币的出价金额（以美分计）

     • bid_strategy ：出价策略（例如“LOWEST_COST”）

     • start_time ， end_time ：可选的开始/结束时间（ISO 8601）

     • access_token （可选）：Meta API 访问令牌

   • 返回：确认新广告组详情

10. mcp_meta_ads_get_ads

• 通过可选的过滤功能获取 Meta Ads 帐户的广告

• 输入：

  • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）

  • account_id ：元广告帐户 ID（格式：act_XXXXXXXXX）

  • limit ：返回广告的最大数量（默认值：10）

  • campaign_id ：可选的广告系列 ID，用于筛选

  • adset_id ：可选的广告组 ID，用于过滤

• 返回：符合条件的广告列表

11. mcp_meta_ads_create_ad

• 使用现有创意创建新广告

• 输入：

  • account_id ：元广告帐户 ID（格式：act_XXXXXXXXX）

  • name ：广告名称

  • adset_id ：放置此广告的广告组 ID

  • creative_id ：要使用的现有创意的 ID

  • status ：初始广告状态（默认值：PAUSED）

  • bid_amount ：可选出价金额（以美分为单位）

  • tracking_specs ：可选的跟踪规范

  • access_token （可选）：Meta API 访问令牌

• 返回：确认新的广告详情

12. mcp_meta_ads_get_ad_details

• 获取有关特定广告的详细信息

• 输入：

  • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）

  • ad_id ：元广告广告 ID

• 返回：指定广告的详细信息

13. mcp_meta_ads_get_ad_creatives

• 获取特定广告的创意详情

• 输入：

  • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）

  • ad_id ：元广告广告 ID

• 返回：创意详情，包括文本、图片和 URL

14. mcp_meta_ads_create_ad_creative

• 使用上传的图片哈希创建新的广告创意

• 输入：

  • account_id ：元广告帐户 ID（格式：act_XXXXXXXXX）

  • name ：创意名称

  • image_hash ：上传图片的哈希值

  • page_id ：广告的 Facebook 页面 ID

  • link_url ：目标网址

  • message ：广告文案/文本

  • headline ：广告标题

  • description ：广告描述

  • call_to_action_type ：CTA 按钮类型（例如“LEARN_MORE”）

  • instagram_actor_id ：可选的 Instagram 帐户 ID

  • access_token （可选）：Meta API 访问令牌

• 返回：确认新的创意细节

15. mcp_meta_ads_upload_ad_image

• 上传用于元广告素材的图片

• 输入：

  • account_id ：元广告帐户 ID（格式：act_XXXXXXXXX）

  • image_path ：要上传的图像文件的路径

  • name ：图像的可选名称

  • access_token （可选）：Meta API 访问令牌

• 返回：带有图像详细信息（包括哈希值）的 JSON 响应

16. mcp_meta_ads_get_ad_image

• 一步获取、下载并可视化元广告图像

• 输入：

  • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）

  • ad_id ：元广告广告 ID

• 返回：可供直接视觉分析的广告图像

17. mcp_meta_ads_update_ad

• 使用新设置更新广告

• 输入：

  • ad_id ：元广告广告 ID

  • status ：更新广告状态（ACTIVE、PAUSED 等）

  • bid_amount ：以账户货币表示的出价金额（以美元美分表示）

  • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）

• 返回：带有更新的广告详情和确认链接的确认

18. 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 访问令牌（如果未提供，将使用缓存令牌）

• 返回：带有更新的广告组详细信息和确认链接的确认

19. mcp_meta_ads_get_insights

• 获取广告系列、广告组、广告或帐户的效果洞察

• 输入：

  • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）

  • object_id ：广告系列、广告组、广告或帐户的 ID

  • time_range ：洞察的时间范围（默认值：最大值）

  • breakdown ：可选细分维度（例如年龄、性别、国家）

  • level ：聚合级别（广告、广告组、广告系列、帐户）

• 返回：指定对象的性能指标

20. mcp_meta_ads_debug_image_download

• 调试图像下载问题并报告详细诊断

• 输入：

  • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）

  • url ：直接测试图像 URL（可选）

  • ad_id ：Meta Ads 广告 ID（可选，未提供 url 时使用）

• 返回：有关图像下载尝试的诊断信息

21. mcp_meta_ads_get_login_link

• 获取可点击的 Meta Ads 身份验证登录链接

• 输入：

  • access_token （可选）：Meta API 访问令牌（如果未提供，将使用缓存令牌）

• 返回：用于 Meta 认证的可点击资源链接

22. mcp_meta-ads_create_budget_schedule

• 为元广告活动创建预算计划。

• 输入：

  • campaign_id ：元广告活动 ID。

  • budget_value ：预算增加金额。

  • budget_value_type ：预算值类型（“ABSOLUTE”或“MULTIPLIER”）。

  • time_start ：高需求期开始的 Unix 时间戳。

  • time_end ：高需求期结束的 Unix 时间戳。

  • access_token （可选）：Meta API 访问令牌。

• 返回：包含创建的预算计划的 ID 的 JSON 字符串或错误消息。