meta-mcp

# Meta Ads MCP Server A Cloudflare Workers MCP server for Meta Ads account setup, campaign management, ad sets, creatives, audiences, reporting, and batch workflows. This repo is built on `xmcp` and exposes a Streamable HTTP MCP endpoint plus browser-facing Meta OAuth routes. ## Open Source / Self-Hosted This repository is intended to be deployed in your own Cloudflare account with your own Meta app credentials. It does not ship with: - a hosted control plane - a shared Meta app - a built-in end-user dashboard - a JWT issuer for your users and workspaces You bring: - your Cloudflare Worker deployment - your Meta developer app - your JWT issuer or auth provider - your own UI or backend that initiates the OAuth flow ## What It Does - Runs as a Cloudflare Worker - Uses direct Meta Graph API `fetch` calls instead of the Meta SDK - Stores Meta user connections per workspace in D1 - Stores short-lived OAuth state in KV - Encrypts stored Meta access tokens - Protects MCP requests with your app-issued JWTs ## Endpoints - `GET /health` - `GET /app` - `POST /mcp` - `GET /oauth/meta/start` - `GET /oauth/meta/callback` ## Auth Model This server is multi-tenant. Every MCP request must include a bearer JWT issued by your app. If you are open-sourcing this project, the important implication is that consumers must wire it into their own auth system. The server does not know how to identify a user or workspace without that JWT. Required JWT claims: - `sub` or `userId` - `workspaceId` - optional `roles` Example payload: ```json { "sub": "user_123", "workspaceId": "workspace_abc", "roles": ["admin"] } ``` Why `/oauth/meta/start` is not a generic public link: - the server must know which workspace the Meta account should be attached to - that workspace context comes from the JWT - without it, the server cannot safely bind the resulting Meta token ## Tool Surface Implemented tool families: - Account and setup - Campaign management - Ad set management - Creative and ads - Audience and targeting - Reporting and insights - Batch helpers The server currently registers 39 tools. ## Project Layout - `src/tools` tool definitions grouped by domain - `src/lib` auth, storage, OAuth, runtime, and Meta client helpers - `src/services` domain-specific Meta service logic - `src/middleware.ts` OAuth routing and MCP JWT auth - `cloudflare-entry.mjs` Worker wrapper entry for Cloudflare-specific route interception - `schema.sql` D1 schema - `test` unit and contract-style tests ## Local Development Install dependencies: ```bash pnpm install ``` Run local dev: ```bash pnpm dev ``` Useful scripts: ```bash pnpm build pnpm test pnpm deploy ``` ## Cloudflare Bindings Required bindings: - D1 database bound as `META_DB` - KV namespace bound as `META_OAUTH_STATE` Required secrets: - `JWT_SECRET` or `JWT_JWKS_URL` - `META_APP_ID` - `META_APP_SECRET` - `META_TOKEN_ENCRYPTION_KEY` - `APP_UI_PASSWORD` for the built-in admin page at `/app` Optional configuration: - `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` Defaults: - `META_GRAPH_VERSION=v25.0` - `META_OAUTH_SCOPES=ads_management,business_management` - `APP_UI_WORKSPACE_ID=workspace_admin` - `APP_UI_USER_ID=app_admin` ## Built-In Admin UI The Worker now includes a small browser UI at `/app`. What it does: - prompts for an admin password - starts the existing Meta OAuth flow without requiring you to manually mint a bearer JWT - shows whether a Meta account is connected for the admin workspace - loads accessible ad accounts using the same service logic as `get_ad_accounts` Required setup: 1. Set `APP_UI_PASSWORD` on the Worker. 2. Make sure `META_REDIRECT_URI` matches your public host, for example: ```text https://meta-mcp.gestalt.xyz/oauth/meta/callback ``` 3. Open: ```text https://meta-mcp.gestalt.xyz/app ``` ## Meta App Setup In your Meta app: 1. Add the Marketing API product. 2. Add a Website platform. 3. Set the Website platform URL to your Worker origin. 4. Set `App Domains` to your Worker domain. 5. Set the callback URL to: ```text https://<your-worker-host>/oauth/meta/callback ``` If your app uses `Facebook Login` or `Facebook Login for Business`, also add that exact callback URL to the product-specific redirect URI settings. For a Worker deployed on `workers.dev`, these fields usually need to match the Worker host exactly. ## Database Apply the D1 schema: ```bash pnpm wrangler d1 execute META_DB --remote --file schema.sql -y ``` Tables: - `meta_connections` - `meta_ad_accounts_cache` ## Deployment Deploy the Worker: ```bash pnpm deploy ``` After deploy: 1. note the public Worker URL 2. set `META_REDIRECT_URI` to `https://<your-worker-host>/oauth/meta/callback` 3. update the same callback in the Meta app settings If you plan to use a separate frontend or dashboard on another origin, allow that origin for post-OAuth browser redirects: ```text META_OAUTH_ALLOWED_RETURN_ORIGINS=https://your-ui.example.com,http://localhost:3000 ``` Use your real frontend origin in production. ## Manual Test Flow ### 1. Generate a short-lived JWT Use the same JWT secret your app uses for the Worker. ```bash 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. Start Meta OAuth ```bash curl -i \ -H "Authorization: Bearer $TOKEN" \ "https://<your-worker-host>/oauth/meta/start?workspace_id=workspace_test" ``` Copy the `Location` header into your browser and complete the Meta login flow. Expected success page: ```text Meta account connected. ``` ### 3. Initialize MCP ```bash 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. List Tools ```bash 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. Call a Real Tool After OAuth succeeds, this should return the accessible ad accounts for that workspace: ```bash 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":{}}}' ``` If you get a connect/reconnect error, the OAuth flow and the MCP call used different `workspaceId` values. ## Notes - Cloudflare `workers.dev` domains can require extra care in Meta app settings. - The Worker entrypoint explicitly intercepts OAuth routes before delegating to the generated XMCP Worker. - The Cloudflare Worker build path is not identical to local `xmcp dev`, so always verify the deployed routes after OAuth-related changes. ## References - [XMCP](https://xmcp.dev/docs) - [Cloudflare Workers](https://developers.cloudflare.com/workers/) - [Meta Marketing API Authorization](https://developers.facebook.com/docs/marketing-api/overview/authorization/)