使用说明

自托管元广告MCP服务器🚀

用于Meta Marketing API的自托管模型上下文协议（MCP）服务器，在具有OAuth 2.0身份验证的Cloudflare Workers上运行。专为多租户SaaS应用程序而构建。

基于 wipsoft/meta-mcp -完全自托管，无第三方依赖！

✨ 特性

✅ 自托管：无第三方依赖关系，在Cloudflare Workers上运行
✅ OAuth 2.0：用户无缝连接自己的Meta Ads帐户
✅ 多住户：非常适合具有多个用户的SaaS平台
✅ 25+工具：完整的Meta Ads API覆盖范围
✅ AI驱动：从自然语言创建活动
✅ 免费等级：Cloudflare免费层每天10万个请求
✅ 最新API：元图API v23.0

🏗️ 建筑

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Your App      │◄──►│ Cloudflare       │◄──►│ Meta Marketing  │
│   (Frontend)    │    │ Worker (MCP)     │    │ API             │
│                 │    │                  │    │                 │
│ - User clicks   │    │ - OAuth flow     │    │ - Campaigns     │
│   "Connect"     │    │ - Token storage  │    │ - Analytics     │
│ - Create        │    │ - API proxy      │    │ - Audiences     │
│   campaigns     │    │ - AI tools       │    │ - Creatives     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │ Cloudflare D1    │
                    │ (Database)       │
                    │                  │
                    │ - User tokens    │
                    │ - Campaigns      │
                    │ - Insights cache │
                    └──────────────────┘

🚀 快速开始

先决条件

Node.js v18+
Cloudflare帐户（免费版有效！）
Meta开发者帐户
牧马人CLI

安装

# Install dependencies
npm install

# Install Wrangler globally
npm install -g wrangler

# Login to Cloudflare
wrangler login

设置（5分钟）

看 设置.md 获取完整的分步说明。

快速版本：

创建元应用程序 在https://developers.facebook.com/apps/

创建Cloudflare资源：

wrangler d1 create meta_ads_mcp
wrangler kv:namespace create OAUTH_STATE

更新 wrangler.jsonc 使用您的资源ID

初始化数据库：

wrangler d1 execute meta_ads_mcp --file=schema.sql

设置秘密：

wrangler secret put META_APP_ID
wrangler secret put META_APP_SECRET

部署：
```
npm run deploy
```

🔧 用法

OAuth流

用户连接他们的Meta Ads帐户：

// Redirect user to start OAuth
window.open(
  'https://your-worker.workers.dev/auth/meta?user_id=USER_ID',
  'Meta OAuth',
  'width=600,height=700'
);

可用端点

GET /health -健康检查
GET /auth/meta?user_id=USER_ID -启动OAuth流
GET /auth/callback -OAuth回调（自动）
POST /auth/disconnect -断开用户帐户连接
GET /sse -MCP SSE端点
POST /mcp -MCP标准端点

MCP工具（25+可用）

认证

check_auth_status -检查用户是否经过身份验证
test_connection -测试服务器连接

账户管理

get_ad_accounts -获取用户的广告帐户

活动管理

get_campaigns -列出活动
create_campaign -创建新活动
update_campaign -更新活动状态/预算
get_campaign_insights -获取性能指标

广告集管理

create_adset -创建具有定位功能的广告集

创造性管理

create_ad_creative -创建广告创意
create_ad -在广告集中创建广告
upload_ad_image -上传图片
get_ad_creatives -列出创意

目标受众

search_interests -搜索目标兴趣
get_custom_audiences -列出自定义受众

AI驱动的工具🤖

create_campaign_from_prompt -自然语言活动创建
analyze_campaign_performance -AI性能分析

示例：创建活动

// Via MCP client
{
  "tool": "create_campaign",
  "arguments": {
    "user_id": "user123",
    "account_id": "act_123456789",
    "name": "Summer Sale 2025",
    "objective": "OUTCOME_LEADS",
    "daily_budget": 5000,
    "status": "PAUSED"
  }
}

答复：

{
  "id": "120210000000000",
  "name": "Summer Sale 2025",
  "status": "PAUSED"
}

📊 为什么选择自助主机？（与移液板相比）

功能	自托管（此）	Pipeboard MCP
成本	✅ 免费（Cloudflare免费版）	⚠️ 付费服务
OAuth	✅ 内置OAuth 2.0⚠️ 通过管道板
控制	✅ 完全控制	❌ 有限
多用户	✅ 本地支持	⚠️ 复杂的设置
定制	✅ 无限制	❌ 有限
最新API	✅ 始终为v23.0+	⚠️ 可能滞后
数据隐私	✅ 您的基础设施	⚠️ 第三方

看 project.md 以进行详细比较。

🔒 安全

✅ 具有CSRF保护的OAuth 2.0（状态参数）
✅ 加密存储在Cloudflare D1中的令牌
✅ 60天令牌到期，自动检查
✅ 无令牌记录或暴露
✅ 速率限制就绪
✅ 通过Wrangler CLI管理的秘密

💰 成本

免费等级（非常适合测试/MVP）

Cloudflare Workers：10万次请求/天
D1数据库：5 GB存储空间
KV命名空间：10万次操作/天
总计：0美元/月 ✨

生产规模（每月100万次请求）

Cloudflare Workers：$5/月（付费计划）
D1和KV：仍然免费（在限制范围内）
总计：约5-10美元/月

与每月50-200美元+每位用户费用的替代品相比！

📚 文档

设置.md -完整的设置指南，包括故障排除
ENV.md -环境变量引用
project.md -架构决策与比较
schema.sql -数据库架构

🛠️ 发展

# Local development
npm run dev

# Visit: http://localhost:8787

# Type checking
npm run type-check

# Format code
npm run format

# Deploy to production
npm run deploy

# View live logs
wrangler tail

# Database commands
wrangler d1 execute meta_ads_mcp --command "SELECT * FROM user_tokens"

🔌 连接到克劳德桌面

添加到您的Claude桌面配置(~/.claude/config.json):

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-worker.workers.dev/sse"
      ]
    }
  }
}

重新启动Claude Desktop，您将看到所有Meta Ads工具！

🔗 连接到Cloudflare AI游乐场

首选https://playground.ai.cloudflare.com/
输入您的MCP服务器URL： https://your-worker.workers.dev/sse
开始在操场上使用Meta Ads工具！

🐛 故障排除

常见问题

“OAuth重定向类型无效”

检查Meta App设置是否与部署的URL完全匹配
无尾随斜线： https://your-worker.workers.dev/auth/callback

“用户未通过身份验证”

首先完成OAuth流程： /auth/meta?user_id=USER_ID
检查数据库： wrangler d1 execute meta_ads_mcp --command "SELECT * FROM user_tokens"

“找不到数据库”

创建数据库： wrangler d1 create meta_ads_mcp
初始化架构： wrangler d1 execute meta_ads_mcp --file=schema.sql
更新 wrangler.jsonc 具有正确的数据库id

“访问令牌已过期”

令牌在60天后过期-重新连接帐户
访问： /auth/meta?user_id=USER_ID

“工具调用失败”

检查您是否已部署机密： wrangler secret put META_APP_ID
测试健康状况： curl https://your-worker.workers.dev/health

看 设置.md 以进行更多故障排除。

🎯 用例

💼 SaaS平台

允许用户连接自己的Meta Ads帐户
通过自然语言为他们创建活动
跨多个帐户显示统一的仪表板

🏢 营销机构

从一个界面管理多个客户端帐户
自动创建和优化活动
实时性能监控

🔧 内部工具

公司营销仪表板
自动每周/每月报告
活动预算优化

🚧 路线图

[]Webhook支持实时活动更新
[]高级AI活动优化（使用Claude）
[]自动A/B测试
[]受众细分建议
[]预算分配AI
[]多平台支持（谷歌广告、领英广告）

🧪 测试

# Test health
curl https://your-worker.workers.dev/health

# Test OAuth (in browser)
https://your-worker.workers.dev/auth/meta?user_id=test-user

# Test MCP tool (via Claude or MCP client)
{
  "tool": "check_auth_status",
  "arguments": { "user_id": "test-user" }
}

📝 许可证

MIT许可证

🙏 鸣谢

灵感来自 wipsoft/meta-mcp
内置 MCP-SDK
由...驱动 Cloudflare Workers
用途元营销API v23.0

🆘 支持

GitHub问题：用于bug和功能请求
Meta API: 元开发者社区
云耀: Cloudflare Discord
MCP协议: MCP GitHub

内置❤️ 面向人工智能驱动的广告未来

没有更昂贵的第三方服务。拥有自己的基础设施。无限缩放。