Meta广告模型协议服务器

一种模型上下文协议服务器，允许人工智能模型访问、分析和管理Meta广告活动，使大型语言模型能够获取性能数据、可视化广告创意，并为Facebook和Instagram平台提供战略洞察。

social-mediamarketing

674 查看 · 2026-07-07 更新

简介

Meta 广告 MCP

一个用于与 Meta 广告 API 交互的模型上下文协议 (MCP) 服务器。此工具使 AI 模型能够通过标准化接口访问、分析和管理 Meta 广告活动，允许大型语言模型（LLMs）检索性能数据、可视化广告创意，并为 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：

# RECOMMENDED: Use with Pipeboard authentication
export PIPEBOARD_API_TOKEN=your_pipeboard_token  # Get your token at https://pipeboard.co
uvx meta-ads-mcp

# Alternative: Use with direct Meta authentication
uvx meta-ads-mcp --app-id YOUR_META_ADS_APP_ID

如果您想安装包：

uv pip install meta-ads-mcp

对于开发（如果您已克隆仓库）：

# From the repository root
uv pip install -e .

使用 pip

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

pip install meta-ads-mcp

安装后，您可以这样运行它：

# RECOMMENDED: Use with Pipeboard authentication
export PIPEBOARD_API_TOKEN=your_pipeboard_token  # Get your token at https://pipeboard.co
python -m meta_ads_mcp

# Alternative: Use with direct Meta authentication
python -m meta_ads_mcp --app-id YOUR_META_ADS_APP_ID

配置

使用 Pipeboard 认证快速启动（推荐）

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

在 Pipeboard.co 注册并生成一个 API 令牌 - 在 https://pipeboard.co 获取您的免费令牌

设置环境变量：

export PIPEBOARD_API_TOKEN=your_pipeboard_token   # 可通过 https://pipeboard.co 获取令牌

运行 meta-ads-mcp 而无需设置 Meta 开发者应用：
```
uvx meta-ads-mcp
```

这种方法提供了更长有效期的令牌（60天），简化了设置过程，并且自动续订令牌。

与 Cursor 或 Claude Desktop 的使用

将以下内容添加到 claude_desktop_config.json 以与 Claude 集成，或添加到 ~/.cursor/mcp.json 以与 Cursor 集成：

"mcpServers": {
  "meta-ads": {
    "command": "uvx",
    "args": ["meta-ads-mcp"],
    "env": {
      "PIPEBOARD_API_TOKEN": "your_pipeboard_token"  // Token obtainable via https://pipeboard.co
    }
  }
}

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

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

可用的 MCP 工具

mcp_meta_ads_get_ad_accounts
- Get ad accounts accessible by a user
- Inputs:
  - access_token (optional): Meta API access token (will use cached token if not provided)
  - user_id: Meta user ID or "me" for the current user
  - limit: Maximum number of accounts to return (default: 10)
- Returns: List of accessible ad accounts with their details
mcp_meta_ads_get_account_info
- Get detailed information about a specific ad account
- Inputs:
  - access_token (optional): Meta API access token (will use cached token if not provided)
  - account_id: Meta Ads account ID (format: act_XXXXXXXXX)
- Returns: Detailed information about the specified account
mcp_meta_ads_get_campaigns
- Get campaigns for a Meta Ads account with optional filtering
- Inputs:
  - access_token (optional): Meta API access token (will use cached token if not provided)
  - account_id: Meta Ads account ID (format: act_XXXXXXXXX)
  - limit: Maximum number of campaigns to return (default: 10)
  - status_filter: Filter by status (empty for all, or 'ACTIVE', 'PAUSED', etc.)
- Returns: List of campaigns matching the criteria
mcp_meta_ads_get_campaign_details
- Get detailed information about a specific campaign
- Inputs:
  - access_token (optional): Meta API access token (will use cached token if not provided)
  - campaign_id: Meta Ads campaign ID
- Returns: Detailed information about the specified campaign
mcp_meta_ads_create_campaign
- Create a new campaign in a Meta Ads account
- Inputs:
  - access_token (optional): Meta API access token (will use cached token if not provided)
  - account_id: Meta Ads account ID (format: act_XXXXXXXXX)
  - name: Campaign name
  - objective: Campaign objective (AWARENESS, TRAFFIC, ENGAGEMENT, etc.)
  - status: Initial campaign status (default: PAUSED)
  - special_ad_categories: List of special ad categories if applicable
  - daily_budget: Daily budget in account currency (in cents)
  - lifetime_budget: Lifetime budget in account currency (in cents)
- Returns: Confirmation with new campaign details
mcp_meta_ads_get_adsets
- Get ad sets for a Meta Ads account with optional filtering by campaign
- Inputs:
  - access_token (optional): Meta API access token (will use cached token if not provided)
  - account_id: Meta Ads account ID (format: act_XXXXXXXXX)
  - limit: Maximum number of ad sets to return (default: 10)
  - campaign_id: Optional campaign ID to filter by
- Returns: List of ad sets matching the criteria
mcp_meta_ads_get_adset_details
- Get detailed information about a specific ad set
- Inputs:
  - access_token (optional): Meta API access token (will use cached token if not provided)
  - adset_id: Meta Ads ad set ID
- Returns: Detailed information about the specified ad set
mcp_meta_ads_get_ads
- Get ads for a Meta Ads account with optional filtering
- Inputs:
  - access_token (optional): Meta API access token (will use cached token if not provided)
  - account_id: Meta Ads account ID (format: act_XXXXXXXXX)
  - limit: Maximum number of ads to return (default: 10)
  - campaign_id: Optional campaign ID to filter by
  - adset_id: Optional ad set ID to filter by
- Returns: List of ads matching the criteria
mcp_meta_ads_get_ad_details
- Get detailed information about a specific ad
- Inputs:
  - access_token (optional): Meta API access token (will use cached token if not provided)
  - ad_id: Meta Ads ad ID
- Returns: Detailed information about the specified ad
mcp_meta_ads_get_ad_creatives
- Get creative details for a specific ad
- Inputs:
  - access_token (optional): Meta API access token (will use cached token if not provided)
  - ad_id: Meta Ads ad ID
- Returns: Creative details including text, images, and URLs
mcp_meta_ads_get_ad_image
- Get, download, and visualize a Meta ad image in one step
- Inputs:
  - access_token (optional): Meta API access token (will use cached token if not provided)
  - ad_id: Meta Ads ad ID
- Returns: The ad image ready for direct visual analysis
mcp_meta_ads_update_ad
- Update an ad with new settings
- Inputs:
  - ad_id: Meta Ads ad ID
  - status: Update ad status (ACTIVE, PAUSED, etc.)
  - bid_amount: Bid amount in account currency (in cents for USD)
  - access_token (optional): Meta API access token (will use cached token if not provided)
- Returns: Confirmation with updated ad details and a confirmation link
mcp_meta_ads_update_adset
- Update an ad set with new settings including frequency caps
- Inputs:
  - adset_id: Meta Ads ad set ID
  - frequency_control_specs: List of frequency control specifications
  - bid_strategy: Bid strategy (e.g., 'LOWEST_COST_WITH_BID_CAP')
  - bid_amount: Bid amount in account currency (in cents for USD)
  - status: Update ad set status (ACTIVE, PAUSED, etc.)
  - targeting: Targeting specifications including targeting_automation
  - access_token (optional): Meta API access token (will use cached token if not provided)
- Returns: Confirmation with updated ad set details and a confirmation link
mcp_meta_ads_get_insights
- Get performance insights for a campaign, ad set, ad or account
- Inputs:
  - access_token (optional): Meta API access token (will use cached token if not provided)
  - object_id: ID of the campaign, ad set, ad or account
  - time_range: Time range for insights (default: maximum)
  - breakdown: Optional breakdown dimension (e.g., age, gender, country)
  - level: Level of aggregation (ad, adset, campaign, account)
- Returns: Performance metrics for the specified object
mcp_meta_ads_debug_image_download
- Debug image download issues and report detailed diagnostics
- Inputs:
  - access_token (optional): Meta API access token (will use cached token if not provided)
  - url: Direct image URL to test (optional)
  - ad_id: Meta Ads ad ID (optional, used if url is not provided)
- Returns: Diagnostic information about image download attempts
mcp_meta_ads_get_login_link
- Get a clickable login link for Meta Ads authentication
- NOTE: This method should only be used if you're using your own Facebook app. If using Pipeboard authentication (recommended), set the PIPEBOARD_API_TOKEN environment variable instead (token obtainable via https://pipeboard.co).
- Inputs:
  - access_token (optional): Meta API access token (will use cached token if not provided)
- Returns: A clickable resource link for Meta authentication

创建 Meta 开发者应用

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

前往 Meta for Developers 并创建一个新的应用
选择 "Consumer" 应用类型
在您的应用设置中，添加 "Marketing API" 产品
配置您的应用的 OAuth 重定向 URI 以包含 http://localhost:8888/callback
记下您的 App ID（客户端 ID），以便与 MCP 一起使用

身份验证

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

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

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

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

Pipeboard 身份验证的好处：

✅ 更长寿命的令牌（60 天）
✅ 无需配置 Meta 开发者应用
✅ 只需一个 API 令牌即可简化设置
✅ 自动续订令牌

要测试 Pipeboard 身份验证流程：

python test_pipeboard_auth.py --api-token YOUR_PIPEBOARD_TOKEN

2. 直接 Meta OAuth（旧版）

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

在进行身份验证时，它会：

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

此方法要求您首先创建一个 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

常见问题

身份验证问题

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

推荐：使用 Pipeboard 认证
- 设置 export PIPEBOARD_API_TOKEN=your_token 并重试
- 这种方式提供更长有效期的令牌和更好的可靠性
- 在 Pipeboard 仪表板中验证您的令牌
对于 App ID 问题（当使用直接认证时）：如果遇到类似 (#200) Provide valid app ID 的错误，请检查以下内容：
- 确保您已正确设置 Meta 开发者应用
- 确认您通过以下方法之一传递了正确的 App ID：
  - 设置 META_APP_ID 环境变量：export META_APP_ID=your_app_id
  - 作为命令行参数传递：meta-ads-mcp --app-id your_app_id

API 错误

如果您从 Meta API 收到错误：

确认您的应用已添加 Marketing API 产品
确保用户在广告账户上有适当的权限
检查您的应用是否有速率限制或其他限制

调试命令

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

# Using direct tool call
mcp_meta_ads_debug_image_download(ad_id="your_ad_id")

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

使用不同的 App ID 运行

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

# Using environment variable
export META_APP_ID=your_app_id
uvx meta-ads-mcp

# Or using command line argument
uvx meta-ads-mcp --app-id=your_app_id

隐私与安全

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

令牌缓存在平台特定的安全位置：
- 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
您不需要为每个命令提供访问令牌；它会自动从缓存中检索。
您可以设置以下环境变量而不是将其作为参数传递：
- META_APP_ID: 您的 Meta App 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 接口测试

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

如果使用直接 Meta 认证（您自己的 Facebook 应用），通过调用 mcp_meta_ads_get_login_link 工具来测试认证
如果使用 Pipeboard 认证（推荐），确保设置了 PIPEBOARD_API_TOKEN 环境变量（令牌可通过 https://pipeboard.co 获取）
通过调用 mcp_meta_ads_get_ad_accounts 来验证账户访问
通过调用 mcp_meta_ads_get_account_info 来检查特定账户详情

这些函数会在必要时自动处理认证，并在需要时提供可点击的登录链接。

故障排除

认证问题

如果你遇到认证问题：

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

API 错误

如果你从 Meta API 收到错误：

确认你的应用程序已添加了 Marketing API 产品
确保用户在广告账户上具有适当的权限
检查你的应用程序是否有速率限制或其他限制

版本

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

import meta_ads_mcp
print(meta_ads_mcp.__version__)

服务配置

[{'mcpServers': {'meta-ads-remote': {'url': 'https://mcp.pipeboard.co/meta-ads-mcp'}}}]

来源

来源：github
链接：https://github.com/nictuku/meta-ads-mcp