Meta MCP Server

The server is multi-tenant and requires every MCP request to include a Bearer JWT issued by your own application. The server uses the workspaceId in the JWT to bind Meta tokens to the correct context.

Required JWT Claims

• sub or userId: The identifier for the user.
• workspaceId: The identifier for the workspace.
• roles (optional): User permissions.

Example JWT Payload

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

The server includes a lightweight browser interface at /app for administrators to manage connections without manually minting JWTs.

Setup Steps

1. Set the APP_UI_PASSWORD secret on your Cloudflare Worker.
2. Ensure META_REDIRECT_URI matches your public host (e.g., https://meta-mcp.example.com/oauth/meta/callback).
3. Access the UI at https://<your-worker-host>/app.

Features

• Prompts for the admin password.
• Initiates the Meta OAuth flow.
• Displays connection status for the admin workspace.
• Lists accessible ad accounts.

The server uses a D1 database to store Meta user connections and ad account caches. Apply the provided schema using Wrangler:

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

This creates the following tables:

• meta_connections
• meta_ad_accounts_cache

To use the server, you must configure a Meta developer app with the following settings:

1. Add Products: Add the Marketing API product.
2. Add Platform: Add a Website platform.
3. Configure Website:
   • Set the Website platform URL to your Worker origin.
   • Set App Domains to your Worker domain.
4. Configure Callback: Set the callback URL to: https://<your-worker-host>/oauth/meta/callback
5. Facebook Login: If using Facebook Login or Facebook Login for Business, ensure the same callback URL is added to the product-specific redirect URI settings.

To develop locally, ensure you have pnpm installed. Use the following commands to install dependencies and start the development environment.

pnpm install
pnpm dev

Other useful scripts include:

• pnpm build: Build the project.
• pnpm test: Run unit and contract tests.
• pnpm deploy: Deploy the Worker.

The ad-set-service.ts module provides high-level service functions for managing Meta Ad Sets. These services can be used to retrieve, create, list, update, delete, or duplicate ad sets within a campaign. Most services return a result object containing a text summary and a data payload formatted for Meta MCP consumers.

Key capabilities include:

• Retrieval: Fetch a single ad set by ID or list ad sets within a specific campaign.
• Lifecycle: Create new ad sets with targeting and budget, update existing ones, or delete them.
• Duplication: Create a copy of an existing ad set with optional overrides.

When using the list<T>() method on MetaGraphClient, the response is wrapped in a MetaListResult<T> object to simplify handling Meta's pagination structure.

MetaListResult<T>

An object containing:

• items: T[]: An array of the requested data type.
• page: MetaPaging: An object containing pagination cursors.

MetaPaging

An object containing optional string cursors for navigating through result sets:

• before?: string: Cursor for the previous page.
• after?: string: Cursor for the next page.
• next?: string: URL or identifier for the next page.
• previous?: string: URL or identifier for the previous page.

export interface MetaPaging {
  before?: string;
  after?: string;
  next?: string;
  previous?: string;
}

export interface MetaListResult<T> {
  items: T[];
  page: MetaPaging;
}

The Meta MCP Admin UI is a built-in web interface for managing Meta OAuth connections and generating MCP tokens. To use the Admin UI, you must first set the APP_UI_PASSWORD environment variable (Worker secret).

If APP_UI_PASSWORD is not set, the login page will display an info banner instructing you to set the secret and reload.

To connect an AI agent or MCP client to your Meta MCP instance, you need a short-lived bearer token. You can generate this via the Admin UI or by calling the /app/api/mcp-token endpoint.

The generated token is intended for clients connecting to the /mcp endpoint and is separate from the browser session cookie.

Example MCP Client Configuration:

{
  "mcpServers": {
    "meta-mcp": {
      "transport": "http",
      "url": "https://your-worker-url.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_GENERATED_TOKEN"
      }
    }
  }
}

{
  "mcpServers": {
    "meta-mcp": {
      "transport": "http",
      "url": "payload.url",
      "headers": {
        "Authorization": "Bearer " + payload.token
      }
    }
  }
}