Meta MCP 连接器

通过 Graph API 为 Meta / Facebook Ads 提供通俗易懂的 MCP 服务器。

可以用自然语言询问广告账户、广告系列、广告组、花费和效果数据——无需了解表名或原始 API 路径。

功能特性

• 从 Facebook Marketing API（Graph API）获取实时数据

• 列出广告账户及其所属的 Business Manager

• 广告系列 / 广告组 / 广告效果数据（花费、展示次数、点击量、购买量）

• 账户级花费仪表盘（account-spend.html）

• 部署到 Cloud Run 时支持 Claude.ai OAuth（MCP_PUBLIC_URL）

Related MCP server: Instagram Ads MCP Server

项目结构

meta-mcp-connector/
├── meta_mcp_server.py    # MCP server + HTTP routes + tools
├── meta_graph.py         # Facebook Graph API client
├── meta_oauth.py         # Claude-compatible OAuth provider
├── account-spend.html    # Spend-by-account dashboard
├── test-accounts.html    # Ad account list test page
├── get-token.html        # Helper to obtain FACEBOOK_ACCESS_TOKEN
├── requirements.txt
├── Dockerfile
├── deploy-cloudrun.ps1   # Deploy to Google Cloud Run
├── .env.example
└── .cursor/mcp.json      # Local Cursor MCP config (example)

本地设置

1. 克隆并安装

git clone https://github.com/YOUR_USERNAME/meta-mcp-connector.git
cd meta-mcp-connector
python -m venv .venv

# Windows
.venv\Scripts\activate

pip install -r requirements.txt
copy .env.example .env

2. 配置 .env

FACEBOOK_APP_ID=your_app_id
FACEBOOK_APP_SECRET=your_app_secret
FACEBOOK_ACCESS_TOKEN=your_user_token_with_ads_read
FACEBOOK_AD_ACCOUNT_ID=114810198697538

令牌要求

• 必须是用户令牌（EAA…），不能是应用令牌（app_id|secret）

• 在 Graph API Explorer 中为你的 FACEBOOK_APP_ID 生成

• 权限：ads_read、ads_management、business_management

使用 get-token.html，或运行服务器后打开 http://127.0.0.1:8001/get-token。

3. 启动服务器

python meta_mcp_server.py --http

4. Cursor MCP 配置

.cursor/mcp.json：

{
  "mcpServers": {
    "meta": {
      "url": "http://127.0.0.1:8001/mcp"
    }
  }
}

启动服务器后，在 Cursor 设置中重新加载 MCP。

MCP 工具

示例提示词

• "列出我的 Meta 广告账户"

• "2026-08-01 至 2026-08-15 的 Meta 广告汇总"

• "WOW Ad Account 最近 7 天的每日花费"

• "昨天按花费排序的顶级广告"

• "按广告系列细分上周的花费"

Google Cloud Run

在 Cloud Run 上托管同一个 HTTP MCP 端点（与 vdp-connector 相同的模式）。Docker 镜像不会内置 .env 或密钥。

前置条件

• 已安装并登录 Google Cloud SDK（gcloud）（gcloud auth login）

• 一个已启用结算的 GCP 项目

• 你的 GCP 项目 ID

• 本地 .env 中已准备好 Facebook 凭据（参见 .env.example）

部署

从本仓库文件夹执行：

# App secret read from .env
.\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID"

# Optional overrides
.\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID" -Region "us-central1" -Service "meta-mcp"

# App secret from a one-line file (gitignored)
.\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID" -SecretFile ".\facebook-app-secret.key"

脚本执行的操作：

1. 启用 Cloud Run、Cloud Build、Secret Manager、Artifact Registry

2. 将 FACEBOOK_APP_SECRET 上传到 Secret Manager（meta-facebook-app-secret）

3. 如果 .env 中设置了 FACEBOOK_ACCESS_TOKEN，则将其上传到 Secret Manager（meta-facebook-access-token）

4. 使用 --source .（Dockerfile）、环境变量和密钥注入进行部署

5. 将 MCP_PUBLIC_URL 设置为服务 URL（Claude OAuth 必需）

6. 打印连接器 URL：https://SERVICE-URL/mcp

部署参数：

• --set-env-vars MCP_TRANSPORT=http,HOST=0.0.0.0,FACEBOOK_APP_ID=…,FACEBOOK_AD_ACCOUNT_ID=…

• --set-secrets FACEBOOK_APP_SECRET=meta-facebook-app-secret:latest,FACEBOOK_ACCESS_TOKEN=meta-facebook-access-token:latest

• --allow-unauthenticated（首次部署时 MCP URL 可用所必需）

• --session-affinity、--max-instances 1、--timeout 300、--port 8080

Cursor（Cloud Run）

部署后，将打印的 URL 填入 .cursor/mcp.json：

"meta": {
  "url": "https://YOUR-CLOUD-RUN-URL/mcp"
}

使用 Cloud Run 时，无需在本地运行 python meta_mcp_server.py 进程。

Claude 自定义连接器

Claude.ai 要求远程自定义连接器使用 OAuth。当设置了 MCP_PUBLIC_URL 时，此服务器内置了兼容 Claude 的 OAuth 提供程序（动态客户端注册，Dynamic Client Registration）（部署脚本会自动设置）。

1. 使用 .\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID" 部署

2. 删除任何旧的损坏连接器

3. 设置 → 连接器 → 添加自定义连接器

4. 精确粘贴：https://YOUR-CLOUD-RUN-URL/mcp（必须包含 /mcp）

5. 在高级设置中将 OAuth Client ID 留空（已启用 DCR）

6. 点击连接——Claude 会自行注册并短暂授权

如果看到 "Couldn't register with … sign-in service"（ofid_…）：

• 确认 URL 以 /mcp 结尾（不是裸的 Cloud Run 主机名）

• 确认服务已启动：打开 https://YOUR-CLOUD-RUN-URL/.well-known/oauth-authorization-server——应看到包含 registration_endpoint 的 JSON

• 确认 MCP_PUBLIC_URL 与服务源匹配（如果更改了 URL，请重新部署）

• 不要粘贴随机的 OAuth Client ID，除非你设置了外部 IdP

验证部署

本地 vs 云端

安全说明

--allow-unauthenticated 使 Cloud Run URL 可公开访问。OAuth 意味着 Claude 必须先完成注册/授权才能使用工具；没有令牌的随机调用者会收到 401。仍应将 URL 视为敏感信息，并在广泛共享前添加更强的认证。

常见问题

1. Claude URL 缺少 /mcp → "Couldn't connect to the server"

2. 未设置 MCP_PUBLIC_URL → OAuth 404 → "Couldn't register with sign-in service"

3. 提交了 .env 或密钥文件

4. OAuth 代码更改后忘记重新部署

5. 未设置 FACEBOOK_ACCESS_TOKEN 就部署 → Graph API 返回权限错误

推送到 GitHub

# Sign in to your new GitHub account first
git credential-manager github login --force

# Create repo on GitHub (browser or gh), then:
git remote add origin https://github.com/YOUR_USERNAME/meta-mcp-connector.git
git add .
git commit -m "Initial commit: Meta MCP connector"
git push -u origin main

安全

• 切勿提交 .env——它已被 gitignore 忽略

• FACEBOOK_ACCESS_TOKEN 是机密信息；如果泄露请轮换

• Cloud Run 部署使用 --allow-unauthenticated 以确保 MCP URL 可访问；设置 MCP_PUBLIC_URL 后，OAuth 可保护工具访问