Fb Ads MCP Server

Facebook广告MCP服务器

一个模型上下文协议（MCP）服务器，用于将AI助手连接到Facebook的广告API。这使得用户可以通过Claude或其他兼容MCP的AI助手直接进行自然语言查询，以获取广告系列数据、见解和广告性能指标。

特点/功能

• 账户管理列出并查看广告账户的详细信息
• 竞选工具检索活动，按状态过滤，获取活动详情
• 广告系列工具在广告系列中访问包含定位信息的广告组
• 广告工具查看单个广告及其创意详情
• 见解与分析获取性能指标（展示量、点击量、花费、点击率等）
• 分页支持使用分页辅助工具处理大型数据集
• 错误处理全面的错误消息和速率限制处理

先决条件

• Python 3.10 或更高版本
• 拥有广告API访问权限的Facebook开发者账户
• 带有Facebook访问令牌的（应用/账户） ads_read 许可；权限

安装

1. 克隆或下载

cd fb-ads-mcp-server

2. 创建虚拟环境

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. 安装依赖项

pip install -r requirements.txt

获取你的Facebook访问令牌

选项1：图API浏览器（快速测试）

1. 首选 脸书图谱API浏览器
2. 选择您的应用或创建一个新应用
3. 点击“生成访问令牌”
4. 加上 ads_read 许可；权限
5. 复制生成的令牌

注来自Graph API浏览器的令牌在1-2小时内过期。如需生产环境使用，请实现适当的OAuth流程。

选项2：Meta开发者门户（长期有效令牌）

1. 首选 开发者版Meta
2. 创建或选择一个应用程序
3. 导航至 工具 → 访问令牌工具
4. 生成一个用户访问令牌 ads_read 许可
5. 可选择兑换为长期有效令牌（60天）

所需权限

• ads_read - 读取广告账户、广告系列和洞察数据的权限

运行服务器

本地测试

python server.py --fb-token YOUR_FACEBOOK_ACCESS_TOKEN

服务器将启动并监听MCP协议请求。

克劳德桌面配置

要在Claude Desktop中使用此MCP服务器，请在您的Claude配置文件中添加以下内容：

macOS/Linux

编辑： ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "fb-ads-mcp-server": {
      "command": "python",
      "args": [
        "/absolute/path/to/fb-ads-mcp-server/server.py",
        "--fb-token",
        "YOUR_FACEBOOK_ACCESS_TOKEN"
      ]
    }
  }
}

Windows

编辑： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fb-ads-mcp-server": {
      "command": "python",
      "args": [
        "C:\\absolute\\path\\to\\fb-ads-mcp-server\\server.py",
        "--fb-token",
        "YOUR_FACEBOOK_ACCESS_TOKEN"
      ]
    }
  }
}

重要的替换 /absolute/path/to/fb-ads-mcp-server/server.py 以及您实际的绝对路径 server.py 文件。

使用虚拟环境与Claude桌面版

如果您想在Claude Desktop中使用虚拟环境：

{
  "mcpServers": {
    "fb-ads-mcp-server": {
      "command": "/absolute/path/to/fb-ads-mcp-server/venv/bin/python",
      "args": [
        "/absolute/path/to/fb-ads-mcp-server/server.py",
        "--fb-token",
        "YOUR_FACEBOOK_ACCESS_TOKEN"
      ]
    }
  }
}

可用工具

账户管理

• 列出广告账户列表() - 列出与您的访问令牌关联的所有广告账户
• 获取广告账户的详细信息（act_id, fields） - 获取特定广告账户的详细信息

活动管理

• 根据广告账户获取活动（get_campaigns_by_adaccount）(act_id, fields, limit, filtering) - 获取广告账户的所有广告系列
• 根据campaign_id获取活动信息（campaign_id, 字段列表） - 获取特定活动的详细信息

广告系列管理

• 根据广告系列获取广告组（campaign_id, 字段, 限制） - 获取广告系列中的所有广告组
• 通过广告集ID获取广告集（adset_id, 字段） - 获取特定广告系列的详细信息

广告管理

• 根据广告组获取广告（adset_id, 字段, 限制） - 检索广告组内的所有广告
• 通过广告ID获取广告信息（ad_id, 字段列表） - 获取特定广告的详细信息

见解与分析

• 获取活动见解（活动ID，字段，日期预设，时间范围） - 获取活动的性能指标
• 获取广告系列洞察（adset_id, 字段, 日期预设） - 获取广告系列的性能指标
• 获取广告洞察（广告ID, 字段, 日期预设） - 获取特定广告的性能指标
• 获取摘要报告(act_id, 日期预设, 时间范围, 限制) - 获取仅包含关键指标的轻量级摘要（已优化以避免上下文限制）

分页

• 获取分页URL(url) - 获取下一页/上一页的结果

使用示例

一旦在Claude Desktop中进行配置，您就可以提出自然语言问题：

基本查询

"List my Facebook ad accounts"
"Show me all campaigns for account act_123456789"
"Get the active campaigns for my ad account"

过滤与细节

"Show me only active campaigns for account act_123456789"
"Get details for campaign 120210000000001"
"What ad sets are in campaign 120210000000001?"

见解与分析

"Show me insights for campaign 120210000000001 for the last 7 days"
"Get performance metrics for ad set 120210000000002"
"What's the CTR and spend for ad 120210000000003?"

自定义字段

"Get campaigns with fields: name, status, budget_remaining, created_time"
"Show ad account details with fields: name, currency, timezone_name"

日期范围

"Get campaign insights for last_30d"
"Show me lifetime performance for this ad set"
"Get insights from 2024-01-01 to 2024-01-31"

通用字段名称

活动字段

• name， objective， status， effective_status
• daily_budget， lifetime_budget， budget_remaining
• created_time， updated_time， start_time， stop_time

广告系列字段

• name， effective_status， optimization_goal
• daily_budget， lifetime_budget
• targeting， bid_amount， billing_event

广告领域

• name， effective_status， creative
• tracking_specs， conversion_specs

洞察指标

• impressions， clicks， spend， reach， frequency
• cpc （每次点击成本）， cpm （每千次展示成本）
• ctr (点击通过率)， conversions， cost_per_conversion

日期预设

• today， yesterday
• last_7d， last_14d， last_30d， last_90d
• this_month， last_month
• this_quarter， last_quarter
• this_year， last_year
• lifetime

错误处理

服务器包含针对以下方面的全面错误处理：

• 缺少令牌如果（条件满足），显示明确的错误信息 --fb-token 未提供
• 无效令牌Facebook API错误被捕获并清晰格式化
• 速率限制HTTP 429 错误已得到妥善处理
• 网络错误超时和连接错误包含有用的信息
• 无效参数类型验证和必填字段检查

安全最佳实践

1. 永远不要提交令牌该 .gitignore 文件排除项 .env 文件和日志
2. 最小权限使用仅包含（某种特定功能或属性）的代币 ads_read 只读访问权限
3. 令牌轮换定期更换你的访问令牌
4. 安全存储安全存储令牌；避免在配置文件中硬编码
5. 监控使用情况请检查您的Meta开发者仪表板，查看是否有异常的API活动

故障排除

“未提供Facebook访问令牌”

确保你正在以管理员身份运行服务器 --fb-token 论点；争论点

python server.py --fb-token YOUR_TOKEN

“无效的OAuth访问令牌”

您的令牌可能已过期。请从Graph API浏览器或Meta开发者门户生成新的令牌。

“不支持的获取请求”

检查您的账户ID是否格式正确（例如。， act_123456789）。

速率限制错误

Facebook对API调用设有限制。如果达到限制，请等待几分钟后再重试。考虑为频繁访问的数据实现缓存。

API版本

这台服务器使用 Facebook 图形 API v22.0检查 脸书的API更新日志 用于版本更新。

局限性

• 只读此服务器仅支持读取操作。写入操作（创建/更新活动）需要额外的权限和实现。
• 令牌过期短期有效令牌在1-2小时内过期。请为生产环境实现令牌刷新逻辑。
• 速率限制根据你的应用层级，受Facebook API速率限制的约束。

未来的改进/增强

• 令牌刷新自动化
• 写入操作（创建/更新广告系列、广告组、广告）
• 支持通过Webhook进行实时更新
• 响应缓存层
• 批量操作以提高效率
• 自定义受众管理
• 广告创意运营
• 活动/变更历史追踪

做出贡献

欢迎投稿！改进方向：

• 增强的错误信息和重试逻辑
• 附加API端点（自定义受众、像素等）
• 性能优化和缓存
• 写操作支持
• 自动化测试套件

许可证

此项目仅供教育和开发用途，按原样提供。

资源

• 脸书营销API文档
• 图API浏览器
• MCP协议文档
• FastMCP框架

支持

对于以下相关问题：

• 这个MCP服务器在这个仓库中打开一个议题
• 脸书API检查 Facebook开发者社区
• MCP协议参观 MCP 文档

______________________________________________________________________

祝广告大获成功！ 🚀