元数据广告MCP服务器

Name: 元数据广告MCP服务器
Author: wipsoft

作者：wipsoft39 星标更新：2025-08-14

安装使用来源：spider==github.com

项目介绍

元营销API MCP服务器

一个全面的模型上下文协议（MCP）服务器，使像Claude这样的AI助手能够通过元营销API与Facebook/Instagram广告数据进行交互。该服务器提供了完整的广告活动生命周期管理、分析、受众定位和创意优化功能。

🚀 功能

活动管理

✅ 创建、更新、暂停、恢复和删除活动
✅ 支持所有活动目标（流量、转化、认知等）
✅ 预算管理和调度
✅ 带有高级定位的广告组创建
✅ 单个广告管理

分析与报告

📊 自定义日期范围的性能洞察
📈 多目标性能比较
📋 CSV/JSON格式的数据导出
🎯 归因建模和转化跟踪
📅 每日性能趋势分析

受众管理

👥 定制受众的创建和管理
🎯 类似受众生成
📏 受众规模估算
🔍 定位建议和见解
🏥 受众健康监控

创意管理

🎨 广告创意的创建和管理
👁️ 跨平台广告预览
🧪 A/B测试设置和指导
📸 创意性能分析

企业功能

🔐 安全的OAuth 2.0认证
⚡ 自动速率限制并带有指数退避
🔄 对大型数据集的支持分页
🛡️ 综合错误处理
📚 丰富的MCP资源以访问上下文数据
🌐 多账户支持

📦 安装与设置

方案1：直接安装（推荐）

npm install -g meta-ads-mcp

方案2：从源码安装

git clone https://github.com/your-org/meta-ads-mcp.git
cd meta-ads-mcp
npm install
npm run build

方案3：自动设置（最简单）

# 首先克隆仓库
git clone https://github.com/your-org/meta-ads-mcp.git
cd meta-ads-mcp

# 运行交互式设置
npm run setup

设置脚本会：

✅ 检查系统要求
✅ 验证您的元访问令牌
✅ 创建Claude桌面配置
✅ 安装依赖项
✅ 测试连接

🔧 配置指南

步骤1：获取元访问令牌

在developers.facebook.com创建一个元应用
添加营销API产品
使用ads_read和ads_management权限生成访问令牌
（可选）设置OAuth以实现自动令牌刷新

CleanShot 2025-06-17 at 15 52 35@2x

步骤2：配置Claude桌面

查找您的配置文件：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json
Linux：~/.config/Claude/claude_desktop_config.json

如果文件不存在，请创建它，并添加以下内容：

基础配置（基于令牌）：

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "meta-ads-mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

高级配置（带OAuth）：

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "meta-ads-mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_access_token_here",
        "META_APP_ID": "your_app_id",
        "META_APP_SECRET": "your_app_secret",
        "META_AUTO_REFRESH": "true",
        "META_BUSINESS_ID": "your_business_id"
      }
    }
  }
}

本地开发配置：

如果您已本地克隆了仓库：

{
  "mcpServers": {
    "meta-ads": {
      "command": "node",
      "args": ["/absolute/path/to/meta-ads-mcp/build/index.js"],
      "env": {
        "META_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

步骤3：配置Cursor

Cursor使用与Claude桌面相同的MCP配置。在您的Cursor设置中添加配置：

打开Cursor设置
转到“扩展”>“Claude”
在JSON设置中添加MCP服务器配置

步骤4：重启客户端

Claude桌面：完全退出并重新启动应用程序
Cursor：重启IDE

步骤5：验证设置

# 运行健康检查以验证一切正常
npm run health-check

# 或者如果全局安装
npx meta-ads-mcp --health-check

🔍 故障排除

常见问题

1. “命令未找到”或“npx”错误

# 如果未安装，请安装Node.js
# macOS: brew install node
# Windows: 从nodejs.org下载
# Linux: 使用您的包管理器

# 验证安装
node --version
npm --version
npx --version

2. 权限错误

# 修复npm权限（macOS/Linux）
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

# 或者不使用sudo安装
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

3. 元API连接问题

# 手动测试您的令牌
curl -G \
  -d "access_token=YOUR_ACCESS_TOKEN" \
  "https://graph.facebook.com/v23.0/me/adaccounts"

4. 检查Claude桌面日志

macOS：~/Library/Logs/Claude/mcp*.log
Windows：%APPDATA%\Claude\logs\mcp*.log

# macOS/Linux - 查看日志
tail -f ~/Library/Logs/Claude/mcp*.log

# Windows - 查看日志
type "%APPDATA%\Claude\logs\mcp*.log"

5. 手动测试服务器

# 直接测试MCP服务器
npx -y meta-ads-mcp

# 或者如果本地安装
node build/index.js

调试模式

通过添加到环境来启用调试日志记录：

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "meta-ads-mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_access_token_here",
        "DEBUG": "mcp:*",
        "NODE_ENV": "development"
      }
    }
  }
}

🌐 网络部署（Vercel）

对于Web应用程序，此服务器也可作为具有OAuth身份验证的Vercel部署：

配置：

部署到Vercel或使用我们的托管版本
在Vercel仪表板中设置环境变量
在Meta开发者控制台中配置OAuth应用
使用Web端点：https://your-project.vercel.app/api/mcp

Web MCP客户端配置：

{
  "mcpServers": {
    "meta-ads-remote": {
      "url": "https://mcp.offerarc.com/api/mcp",
      "headers": {
        "Authorization": "Bearer your_session_token"
      }
    }
  }
}

注意：您需要首先在https://mcp.offerarc.com/api/auth/login进行身份验证以获取会话令牌。

远程MCP配置（mcp-remote）

对于Vercel部署，使用mcp-remote来桥接HTTP到stdio：

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.offerarc.com/api/mcp",
        "--header",
        "Authorization:${META_AUTH_HEADER}"
      ],
      "env": {
        "META_AUTH_HEADER": "Bearer your_session_token_here"
      }
    }
  }
}

🛠️ 可用工具

此MCP服务器提供25种全面的工具，涵盖所有主要的元广告类别：

📊 分析与见解（3种工具）

get_insights - 获取详细的性能指标（展示次数、点击次数、ROAS、CTR、CPC等）
compare_performance - 多个活动/广告的并排性能比较
export_insights - 将性能数据导出为JSON或CSV格式

📈 活动管理（4种工具）

create_campaign - 使用完整配置创建新的广告活动（包括特殊广告类别）
update_campaign - 修改现有活动（名称、预算、状态等）
pause_campaign - 暂停活动
resume_campaign - 恢复/激活暂停的活动

🎯 广告组管理（2种工具）

create_ad_set - 使用详细定位、预算和优化目标创建广告组
list_ad_sets - 列出并筛选活动中的广告组

📱 广告管理（2种工具）

create_ad - 使用创意ID在广告组内创建单个广告
list_ads - 列出并筛选广告，按广告组、活动或账户

👥 受众管理（4种工具）

list_audiences - 列出账户的所有定制受众
create_custom_audience - 从各种来源创建定制受众
create_lookalike_audience - 从源受众生成类似受众
get_audience_info - 获取特定受众的详细信息

🎨 创意管理（2种工具）

list_ad_creatives - 列出账户的所有广告创意
create_ad_creative - 使用丰富的规格创建新的广告创意（支持外部图像URL）

🔧 账户及基础工具（3种工具）

health_check - 综合的身份验证和服务器状态检查
get_ad_accounts - 列出可访问的元广告账户
get_campaigns - 列出活动并提供过滤选项

🔐 认证工具（1种工具）

get_token_info - 令牌验证和信息检索

🩺 诊断工具（2种工具）

diagnose_campaign_readiness - 检查活动状态并识别广告组创建问题
check_account_setup - 综合账户验证和设置验证

🛠️ 使用示例

测试连接

检查元营销API服务器的健康状况和身份验证状态

分析与性能洞察

获取我的Deal Draft活动在过去30天内的详细性能洞察，包括展示次数、点击次数、ROAS和CTR

比较我过去季度的前三名活动的并排性能

导出我上个月所有活动的性能数据为CSV格式

活动管理

创建一个新的流量活动，命名为"Holiday Sale 2024"，每日预算为$50，目标为OUTCOME_TRAFFIC

更新我现有的活动预算为$100每日，并将名称更改为"Black Friday Special"

暂停所有CPC高于$2.00的活动

恢复我暂停的"Summer Collection"活动

完整活动设置（活动→广告组→广告）

创建一个完整的"Test 3"活动设置：1) 创建目标为OUTCOME_LEADS的活动，2) 创建针对美国年龄在25-45岁之间对创业感兴趣用户的广告组，3) 使用现有创意创建4个不同的广告

为我现有的活动创建一个针对年龄在30-50岁之间的女性用户，对商业和个人发展感兴趣的广告组

在我的广告组中使用创意ID 123456创建一个新的广告，并将其命名为"Headline Test A"

故障排除与诊断

诊断我的"Test 3"活动，查看其是否准备好创建广告组并识别任何潜在问题

检查我的账户设置，验证支付方式、业务验证和广告账户权限

检查为什么我的广告组创建失败，并获得针对我的账户设置的具体建议

受众管理

列出我所有的定制受众，并显示它们的大小和状态

创建一个名为"Website Visitors"的定制受众，从访问过我的网站的人中创建

基于我的"High Value Customers"受众，在美国创建一个5%的类似受众

获取我的"Newsletter Subscribers"受众的详细信息，包括健康状态

创意管理

列出我所有的广告创意，并显示它们的性能数据

为我的假日活动创建一个新的广告创意，使用来自我网站的外部图像URL和特定消息

账户管理

显示我可访问的所有元广告账户及其货币和时区

获取我当前访问令牌的信息，包括权限和到期时间

📚 资源访问

服务器通过MCP资源提供丰富的上下文数据：

meta://campaigns/{account_id} - 活动概览
meta://insights/account/{account_id} - 性能仪表盘
meta://audiences/{account_id} - 受众洞察
meta://audience-health/{account_id} - 受众健康报告

🔧 环境变量

必需

META_ACCESS_TOKEN=your_access_token_here

可选

META_APP_ID=your_app_id                    # 用于OAuth
META_APP_SECRET=your_app_secret            # 用于OAuth
META_BUSINESS_ID=your_business_id          # 用于特定业务操作
META_API_VERSION=v23.0                     # API版本（默认：v23.0）
META_API_TIER=standard                     # 'development'或'standard'
META_AUTO_REFRESH=true                     # 启用自动令牌刷新
META_REFRESH_TOKEN=your_refresh_token      # 用于令牌刷新

📖 文档

快速设置指南 - 5分钟设置说明
设置指南 - 完整的安装和配置
工具参考 - 所有可用工具和资源
示例配置 - 示例配置文件

🏗️ 架构

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Claude AI     │◄──►│ MCP Server       │◄──►│ Meta Marketing  │
│                 │    │                  │    │ API             │
│ - 自然          │    │ - 身份验证       │    │                 │
│   语言          │    │ - 速率限制       │    │ - 活动          │
│ - 工具调用      │    │ - 错误处理       │    │ - 分析         │
│ - 资源          │    │ - 数据转换       │    │ - 受众         │
│   访问          │    │ - 分页           │    │ - 创意         │
└─────────────────┘    └──────────────────┘    └─────────────────┘

核心组件

元API客户端：处理身份验证、速率限制和API通信
工具处理器：25种工具覆盖分析、活动、广告组、广告、受众、创意和诊断
资源提供者：为AI理解提供上下文数据访问
错误管理：强大的错误处理和自动重试
速率限制器：智能速率限制并带有每个账户跟踪

🔒 安全与最佳实践

令牌安全

✅ 环境变量配置
✅ 不记录或暴露令牌
✅ 自动令牌验证
✅ 安全凭证管理

API管理

✅ 遵守速率限制
✅ 指数退避重试
✅ 请求验证
✅ 错误边界保护

数据隐私

✅ 符合元数据使用政策
✅ 不持久存储数据
✅ 安全API通信
✅ 支持审计轨迹

⚡ 性能

速率限制

开发层：每5分钟60次API调用
标准层：每5分钟9000次API调用
自动管理：内置的速率限制和重试逻辑

优化

🚀 并发请求处理
📦 高效分页处理