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:

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

pnpm install

Run local dev:

pnpm dev

Useful scripts:

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:

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

3. Open:

https://meta-mcp.gestalt.xyz/app

Met

... View full README on GitHub