Meta Ads MCP

元广告 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 字符串或错误消息。