Meta Ads MCP

Meta Ads MCP

用于与 Meta 广告 API 交互的模型上下文协议 (MCP) 服务器

pipeboard-co

开发者工具
访问服务器

README

Meta Ads MCP

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

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

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

Meta Ads MCP 运行示例：直接在 Claude 或您最喜欢的 MCP 客户端中可视化广告效果指标和创意细节，其中包含有关广告系列覆盖范围、互动和成本的丰富见解

功能

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

安装

使用 uv (推荐)

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

uvx meta-ads-mcp --app-id YOUR_META_ADS_APP_ID

如果您想安装该软件包：

uv pip install meta-ads-mcp

用于开发（如果您已克隆存储库）：

# 从存储库根目录
uv pip install -e .

使用 pip

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

pip install meta-ads-mcp

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

python -m meta_ads_mcp

配置

在 Cursor 中与 Claude 一起使用

将此添加到您的 claude_desktop_config.json 以与 Cursor 中的 Claude 集成：

"mcpServers": {
  "meta-ads": {
    "command": "uvx",
    "args": ["meta-ads-mcp", "--app-id", "YOUR_META_ADS_APP_ID"]
  }
}

可用的 MCP 工具

  1. mcp_meta_ads_get_ad_accounts

    • 获取用户可以访问的广告帐户
    • 输入：
      • access_token（可选）：Meta API 访问令牌（如果未提供，将使用缓存的令牌）
      • user_id：Meta 用户 ID 或 "me" 表示当前用户
      • limit：要返回的最大帐户数（默认值：10）
    • 返回：包含其详细信息的可以访问的广告帐户列表

  2. mcp_meta_ads_get_account_info

    • 获取有关特定广告帐户的详细信息
    • 输入：
      • access_token（可选）：Meta API 访问令牌（如果未提供，将使用缓存的令牌）
      • account_id：Meta Ads 帐户 ID（格式：act_XXXXXXXXX）
    • 返回：有关指定帐户的详细信息

  3. mcp_meta_ads_get_campaigns

    • 获取 Meta Ads 帐户的广告系列，并可选择进行过滤
    • 输入：
      • access_token（可选）：Meta API 访问令牌（如果未提供，将使用缓存的令牌）
      • account_id：Meta Ads 帐户 ID（格式：act_XXXXXXXXX）
      • limit：要返回的最大广告系列数（默认值：10）
      • status_filter：按状态过滤（空表示全部，或 'ACTIVE'、'PAUSED' 等）
    • 返回：与条件匹配的广告系列列表

  4. mcp_meta_ads_get_campaign_details

    • 获取有关特定广告系列的详细信息
    • 输入：
      • access_token（可选）：Meta API 访问令牌（如果未提供，将使用缓存的令牌）
      • campaign_id：Meta Ads 广告系列 ID
    • 返回：有关指定广告系列的详细信息

  5. mcp_meta_ads_create_campaign

    • 在 Meta Ads 帐户中创建一个新的广告系列
    • 输入：
      • access_token（可选）：Meta API 访问令牌（如果未提供，将使用缓存的令牌）
      • account_id：Meta Ads 帐户 ID（格式：act_XXXXXXXXX）
      • name：广告系列名称
      • objective：广告系列目标（AWARENESS、TRAFFIC、ENGAGEMENT 等）
      • status：初始广告系列状态（默认值：PAUSED）
      • special_ad_categories：如果适用，则为特殊广告类别列表
      • daily_budget：帐户货币的每日预算（以美分为单位）
      • lifetime_budget：帐户货币的终身预算（以美分为单位）
    • 返回：包含新广告系列详细信息的确认信息

  6. mcp_meta_ads_get_adsets

    • 获取 Meta Ads 帐户的广告组，并可选择按广告系列进行过滤
    • 输入：
      • access_token（可选）：Meta API 访问令牌（如果未提供，将使用缓存的令牌）
      • account_id：Meta Ads 帐户 ID（格式：act_XXXXXXXXX）
      • limit：要返回的最大广告组数（默认值：10）
      • campaign_id：用于过滤的可选广告系列 ID
    • 返回：与条件匹配的广告组列表

  7. mcp_meta_ads_get_adset_details

    • 获取有关特定广告组的详细信息
    • 输入：
      • access_token（可选）：Meta API 访问令牌（如果未提供，将使用缓存的令牌）
      • adset_id：Meta Ads 广告组 ID
    • 返回：有关指定广告组的详细信息

  8. mcp_meta_ads_get_ads

    • 获取 Meta Ads 帐户的广告，并可选择进行过滤
    • 输入：
      • access_token（可选）：Meta API 访问令牌（如果未提供，将使用缓存的令牌）
      • account_id：Meta Ads 帐户 ID（格式：act_XXXXXXXXX）
      • limit：要返回的最大广告数（默认值：10）
      • campaign_id：用于过滤的可选广告系列 ID
      • adset_id：用于过滤的可选广告组 ID
    • 返回：与条件匹配的广告列表

  9. mcp_meta_ads_get_ad_details

    • 获取有关特定广告的详细信息
    • 输入：
      • access_token（可选）：Meta API 访问令牌（如果未提供，将使用缓存的令牌）
      • ad_id：Meta Ads 广告 ID
    • 返回：有关指定广告的详细信息

  10. mcp_meta_ads_get_ad_creatives

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

  11. mcp_meta_ads_get_ad_image

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

  12. mcp_meta_ads_update_ad

    • 使用新设置更新广告
    • 输入：
      • ad_id：Meta Ads 广告 ID
      • status：更新广告状态（ACTIVE、PAUSED 等）
      • bid_amount：帐户货币的出价金额（美元以美分为单位）
      • access_token（可选）：Meta API 访问令牌（如果未提供，将使用缓存的令牌）
    • 返回：包含更新的广告详细信息和确认链接的确认信息

  13. mcp_meta_ads_update_adset

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

  14. mcp_meta_ads_get_insights

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

  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 身份验证的可点击登录链接
    • 输入：
      • access_token（可选）：Meta API 访问令牌（如果未提供，将使用缓存的令牌）
    • 返回：用于 Meta 身份验证的可点击资源链接

创建 Meta 开发者应用

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

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

身份验证

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

1. Pipeboard 身份验证（推荐）

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

  1. 设置您的 Pipeboard 帐户并从您的仪表板生成 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 开发者应用
  • 只需一个 API 令牌即可进行更简单的设置
  • 自动令牌续订

要测试 Pipeboard 身份验证流程：

python test_pipeboard_auth.py --api-token YOUR_PIPEBOARD_TOKEN

2. 直接 Meta OAuth（旧版）

专为桌面应用设计的传统 OAuth 2.0 流程。进行身份验证时，它将：

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

此方法要求您首先创建一个 Meta 开发者应用。

故障排除和日志记录

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

常见问题

应用 ID 问题

如果您遇到类似 (#200) Provide valid app ID 的错误，请检查以下内容：

  1. 确保您已正确设置 Meta 开发者应用
  2. 验证您是否使用以下方法之一传递了正确的应用 ID：
    • 设置 META_APP_ID 环境变量：export META_APP_ID=your_app_id
    • 将其作为命令行参数传递：meta-ads-mcp --app-id your_app_id

身份验证错误

可以在日志文件中跟踪身份验证错误。检查：

  • 令牌过期问题
  • 应用权限问题
  • 连接错误

调试命令

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

# 使用直接工具调用
mcp_meta_ads_debug_image_download(ad_id="your_ad_id")

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

使用不同的应用 ID 运行

如果您需要为不同的目的使用不同的 Meta 应用 ID：

# 使用环境变量
export META_APP_ID=your_app_id
uvx meta-ads-mcp

# 或使用命令行参数
uvx meta-ads-mcp --app-id=your_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 应用 ID（客户端 ID）- 用于直接 OAuth 方法
    • PIPEBOARD_API_TOKEN：您的 Pipeboard API 令牌 - 用于 Pipeboard 身份验证方法

测试

CLI 测试

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

python test_meta_ads_auth.py --app-id YOUR_APP_ID

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

python test_meta_ads_auth.py --app-id YOUR_APP_ID --force-login

LLM 接口测试

将 Meta Ads MCP 与 LLM 接口（如 Claude）一起使用时：

  1. 通过调用 mcp_meta_ads_get_login_link 工具来测试身份验证
  2. 通过调用 mcp_meta_ads_get_ad_accounts 来验证帐户访问权限
  3. 使用 mcp_meta_ads_get_account_info 检查特定帐户详细信息

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

故障排除

身份验证问题

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

  1. 使用 LLM 接口时：

    • 使用 mcp_meta_ads_get_login_link 工具生成新的身份验证链接
    • 确保您单击该链接并在浏览器中完成授权流程
    • 检查回调服务器是否正常运行（该工具将报告此情况）

  2. 使用 Pipeboard 身份验证时：

    • 验证您的 PIPEBOARD_API_TOKEN 是否已正确设置
    • 检查您是否需要通过访问提供的登录 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. 验证您的应用是否已添加 Marketing API 产品
  2. 确保用户对广告帐户具有适当的权限
  3. 检查您的应用是否存在速率限制或其他限制

版本控制

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

import meta_ads_mcp
print(meta_ads_mcp.__version__)

推荐服务器

Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
MCP Package Docs Server

MCP Package Docs Server

促进大型语言模型高效访问和获取 Go、Python 和 NPM 包的结构化文档，通过多语言支持和性能优化来增强软件开发。

精选
本地
TypeScript
Claude Code MCP

Claude Code MCP

一个实现了 Claude Code 作为模型上下文协议（Model Context Protocol, MCP）服务器的方案，它可以通过标准化的 MCP 接口来使用 Claude 的软件工程能力（代码生成、编辑、审查和文件操作）。

精选
本地
JavaScript
@kazuph/mcp-taskmanager

@kazuph/mcp-taskmanager

用于任务管理的模型上下文协议服务器。它允许 Claude Desktop（或任何 MCP 客户端）在基于队列的系统中管理和执行任务。

精选
本地
JavaScript
mermaid-mcp-server

mermaid-mcp-server

一个模型上下文协议 (MCP) 服务器，用于将 Mermaid 图表转换为 PNG 图像。

精选
JavaScript
Jira-Context-MCP

Jira-Context-MCP

MCP 服务器向 AI 编码助手（如 Cursor）提供 Jira 工单信息。

精选
TypeScript
Linear MCP Server

Linear MCP Server

一个模型上下文协议（Model Context Protocol）服务器，它与 Linear 的问题跟踪系统集成，允许大型语言模型（LLM）通过自然语言交互来创建、更新、搜索和评论 Linear 问题。

精选
JavaScript
Sequential Thinking MCP Server

Sequential Thinking MCP Server

这个服务器通过将复杂问题分解为顺序步骤来促进结构化的问题解决，支持修订，并通过完整的 MCP 集成来实现多条解决方案路径。

精选
Python
Curri MCP Server

Curri MCP Server

通过管理文本笔记、提供笔记创建工具以及使用结构化提示生成摘要，从而实现与 Curri API 的交互。

官方
本地
JavaScript