AI导哈

Meta广告管理服务器

一个基于Cloudflare Workers的Meta广告账户设置、活动管理、广告集、创意、受众、报告和批量工作流的MCP服务器。

  • by brijr
  • TypeScript
  • 本地部署
  • 201 星标
  • 更新于
在 GitHub 查看 brijr/meta-ads-mcp

使用说明

元广告MCP服务器

Cloudflare Workers MCP服务器，用于Meta Ads帐户设置、活动管理、广告集、创意、受众、报告和批处理工作流。

此回购基于 xmcp 并公开了一个可流式传输的HTTP MCP端点以及面向浏览器的Meta OAuth路由。

开源/自托管

此存储库旨在使用您自己的Meta应用程序凭据部署在您自己的Cloudflare帐户中。

它不附带：

  • 托管控制平面
  • 一个共享的Meta应用
  • 内置的终端用户仪表板
  • 为您的用户和工作区提供JWT发行器

你带来：

  • 您的Cloudflare Worker部署
  • 你的Meta开发者应用
  • 您的JWT发行者或身份验证提供者
  • 您自己的UI或后端启动OAuth流

它的作用

  • 以Cloudflare Worker身份运行
  • 使用直接的Meta Graph API fetch 调用而不是Meta SDK
  • 在D1中存储每个工作区的元用户连接
  • 在KV中存储短期OAuth状态
  • 加密存储的Meta访问令牌
  • 使用您的应用程序发布的JWT保护MCP请求

端点

  • GET /health
  • GET /app
  • POST /mcp
  • GET /oauth/meta/start
  • GET /oauth/meta/callback

身份验证模型

此服务器是多租户服务器。每个MCP请求都必须包含您的应用程序发出的承载JWT。

如果你将这个项目开源，重要的含义是消费者必须将其连接到自己的身份验证系统中。没有JWT，服务器不知道如何识别用户或工作区。

所需JWT索赔：

  • sub 或 userId
  • workspaceId
  • 可选的 roles

有效载荷示例：

{
  "sub": "user_123",
  "workspaceId": "workspace_abc",
  "roles": ["admin"]
}

为什么 /oauth/meta/start 不是通用公共链接：

  • 服务器必须知道元帐户应附加到哪个工作区
  • 工作空间上下文来自JWT
  • 没有它，服务器就无法安全地绑定生成的Meta令牌

刀具表面

已实施的工具系列：

  • 帐户和设置
  • 活动管理
  • 广告集管理
  • 创意和广告
  • 受众和目标
  • 报告和见解
  • 批处理助手

服务器当前注册了39个工具。

项目布局

  • src/tools 按域分组的工具定义
  • src/lib auth、存储、OAuth、运行时和Meta客户端帮助程序
  • src/services 域特定元服务逻辑
  • src/middleware.ts OAuth路由和MCP JWT认证
  • cloudflare-entry.mjs Cloudflare特定路由拦截的Worker包装器条目
  • schema.sql D1架构
  • test 单位和合同风格测试

本地开发

安装依赖项：

pnpm install

运行本地dev：

pnpm dev

有用的脚本：

pnpm build
pnpm test
pnpm deploy

Cloudflare绑定

所需绑定：

  • D1数据库绑定为 META_DB
  • KV命名空间绑定为 META_OAUTH_STATE

所需机密：

  • JWT_SECRET 或 JWT_JWKS_URL
  • META_APP_ID
  • META_APP_SECRET
  • META_TOKEN_ENCRYPTION_KEY
  • APP_UI_PASSWORD 对于内置管理页面，请访问 /app

可选配置：

  • JWT_ISSUER
  • JWT_AUDIENCE
  • APP_SESSION_SECRET
  • APP_UI_WORKSPACE_ID
  • APP_UI_USER_ID
  • META_REDIRECT_URI
  • META_GRAPH_VERSION
  • META_OAUTH_SCOPES
  • META_OAUTH_ALLOWED_RETURN_ORIGINS

默认值：

  • META_GRAPH_VERSION=v25.0
  • META_OAUTH_SCOPES=ads_management,business_management
  • APP_UI_WORKSPACE_ID=workspace_admin
  • APP_UI_USER_ID=app_admin

内置管理UI

Worker现在包括一个小型浏览器UI，位于 /app.

它的作用：

  • 提示输入管理员密码
  • 启动现有的Meta OAuth流，而不需要您手动创建承载JWT
  • 显示管理员工作区是否连接了Meta帐户
  • 使用与相同的服务逻辑加载可访问的广告帐户 get_ad_accounts

所需设置：

  1. 集 APP_UI_PASSWORD 关于工人。
  2. 确保 META_REDIRECT_URI 匹配您的公共主机，例如：
https://meta-mcp.gestalt.xyz/oauth/meta/callback
  1. 打开：
https://meta-mcp.gestalt.xyz/app

元应用程序设置

在Meta应用程序中：

  1. 添加营销API产品。
  2. 添加网站平台。
  3. 将网站平台URL设置为您的Worker来源。
  4. 集 App Domains 转到您的Worker域。
  5. 将回调URL设置为：
https://<your-worker-host>/oauth/meta/callback

如果你的应用程序使用 Facebook Login 或 Facebook Login for Business，还将该确切的回调URL添加到产品特定的重定向URI设置中。

对于部署在上的Worker workers.dev，这些字段通常需要与Worker主机完全匹配。

数据库

应用D1模式：

pnpm wrangler d1 execute META_DB --remote --file schema.sql -y

桌子：

  • meta_connections
  • meta_ad_accounts_cache

部署

部署Worker：

pnpm deploy

部署后：

  1. 注意公共Worker URL
  2. 集 META_REDIRECT_URI 到 https://<your-worker-host>/oauth/meta/callback
  3. 在Meta应用程序设置中更新相同的回调

如果您计划在另一个源上使用单独的前端或仪表板，请允许该源进行OAuth后浏览器重定向：

META_OAUTH_ALLOWED_RETURN_ORIGINS=https://your-ui.example.com,http://localhost:3000

在生产中使用您真正的前端来源。

手动测试流程

1.生成一个短暂的JWT

使用您的应用程序用于Worker的相同JWT密钥。

export JWT_SECRET="YOUR_JWT_SECRET"

TOKEN=$(node --input-type=module <<'NODE'
import { SignJWT } from 'jose';

const secret = new TextEncoder().encode(process.env.JWT_SECRET);
const token = await new SignJWT({ workspaceId: 'workspace_test', roles: ['admin'] })
  .setProtectedHeader({ alg: 'HS256' })
  .setSubject('user_test')
  .setIssuedAt()
  .setExpirationTime('10m')
  .sign(secret);

console.log(token);
NODE
)

2.启动Meta OAuth

curl -i \
  -H "Authorization: Bearer $TOKEN" \
  "https://<your-worker-host>/oauth/meta/start?workspace_id=workspace_test"

复制 Location 进入浏览器并完成Meta登录流程。

预期成功页面：

Meta account connected.

3.初始化MCP

curl -s https://<your-worker-host>/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"manual-test","version":"1.0.0"}}}'

4.列出工具

curl -s https://<your-worker-host>/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":"tools-1","method":"tools/list","params":{}}'

5.调用真正的工具

OAuth成功后，这应该返回该工作区的可访问广告帐户：

curl -s https://<your-worker-host>/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":"call-1","method":"tools/call","params":{"name":"get_ad_accounts","arguments":{}}}'

如果您遇到连接/重新连接错误，OAuth流和MCP调用将使用不同的 workspaceId 价值观。

备注

  • 云耀 workers.dev 在Meta应用程序设置中，域可能需要额外的关注。
  • Worker入口点在委托给生成的XMCP Worker之前显式拦截OAuth路由。
  • Cloudflare Worker构建路径与本地路径不同 xmcp dev，因此请务必在OAuth相关更改后验证部署的路由。

参考文献

相关 MCP