Meta Marketing API MCP Server

Interact with Facebook and Instagram advertising data using the Meta Marketing API.

A Cloudflare Workers MCP server for Meta Ads account setup, campaign management, ad sets, creatives, audiences, reporting, and batch workflows.

This repo is built onxmcpand exposes a Streamable HTTP MCP endpoint plus browser-facing Meta OAuth routes.

This repository is intended to be deployed in your own Cloudflare account with your own Meta app credentials.

- a hosted control plane
- a shared Meta app
- a built-in end-user dashboard
- a JWT issuer for your users and workspaces

- your Cloudflare Worker deployment
- your Meta developer app
- your JWT issuer or auth provider
- your own UI or backend that initiates the OAuth flow

- Runs as a Cloudflare Worker
- Uses direct Meta Graph APIfetchcalls 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

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

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.

- suboruserId
- workspaceId
- optionalroles

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

Why/oauth/meta/startis 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

- 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.

- src/toolstool definitions grouped by domain
- src/libauth, storage, OAuth, runtime, and Meta client helpers
- src/servicesdomain-specific Meta service logic
- src/middleware.tsOAuth routing and MCP JWT auth
- cloudflare-entry.mjsWorker wrapper entry for Cloudflare-specific route interception
- schema.sqlD1 schema
- testunit and contract-style tests

- D1 database bound asMETA_DB
- KV namespace bound asMETA_OAUTH_STATE

- JWT_SECRETorJWT_JWKS_URL
- META_APP_ID
- META_APP_SECRET
- META_TOKEN_ENCRYPTION_KEY
- APP_UI_PASSWORDfor the built-in admin page at/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

The Worker now includes a small browser UI at/app.

- 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 asget_ad_accounts
- SetAPP_UI_PASSWORDon the Worker.
- Make sureMETA_REDIRECT_URImatches your public host, for example:

https://meta-mcp.gestalt.xyz/oauth/meta/callback

- Add the Marketing API product.
- Add a Website platform.
- Set the Website platform URL to your Worker origin.
- SetApp Domainsto your Worker domain.
- Set the callback URL to:

https://<your-worker-host>/oauth/meta/callback

If your app usesFacebook LoginorFacebook Login for Business, also add that exact callback URL to the product-specific redirect URI settings.

For a Worker deployed onworkers.dev, these fields usually need to match the Worker host exactly.

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

- note the public Worker URL
- setMETA_REDIRECT_URItohttps://<your-worker-host>/oauth/meta/callback
- 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:

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

Use your real frontend origin in production.

Use the same JWT secret your app uses for the Worker.

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 )

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

Copy theLocationheader into your browser and complete the Meta login flow.

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"}}}'

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":{}}'

After OAuth succeeds, this should return the accessible ad accounts for that workspace:

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 differentworkspaceIdvalues.

- Cloudflareworkers.devdomains 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 localxmcp dev, so always verify the deployed routes after OAuth-related changes.

- XMCP
- Cloudflare Workers
- Meta Marketing API Authorization

An MCP server for accessing Twitter Ads data, powered by the CData JDBC Driver.