Meta Marketing API MCP Server

Interaja com dados de publicidade do Facebook e Instagram usando a Meta Marketing API.

GitHub
200
Experimente este MCPPatrocinado

Documentação

Meta Ads MCP Server

Um servidor MCP do Cloudflare Workers para configuração de contas do Meta Ads, gerenciamento de campanhas, conjuntos de anúncios, criativos, públicos, relatórios e fluxos de trabalho em lote.

Este repositório é construído sobre xmcp e expõe um endpoint MCP HTTP Streamable, além de rotas de OAuth da Meta voltadas para o navegador.

Código Aberto / Auto-hospedado

Este repositório é destinado a ser implantado na sua própria conta Cloudflare com as credenciais do seu próprio aplicativo Meta.

Ele não inclui:

  • um plano de controle hospedado
  • um aplicativo Meta compartilhado
  • um painel de usuário final integrado
  • um emissor de JWT para seus usuários e espaços de trabalho

Você fornece:

  • sua implantação do Cloudflare Worker
  • seu aplicativo de desenvolvedor Meta
  • seu emissor de JWT ou provedor de autenticação
  • sua própria interface ou backend que inicia o fluxo OAuth

O Que Ele Faz

  • Executa como um Cloudflare Worker
  • Usa chamadas diretas à Meta Graph API fetch em vez do SDK da Meta
  • Armazena conexões de usuários Meta por espaço de trabalho no D1
  • Armazena estado OAuth de curta duração no KV
  • Criptografa tokens de acesso Meta armazenados
  • Protege solicitações MCP com JWTs emitidos pelo seu aplicativo

Endpoints

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

Modelo de Autenticação

Este servidor é multi-tenant. Toda solicitação MCP deve incluir um JWT bearer emitido pelo seu aplicativo.

Se você está disponibilizando este projeto como código aberto, a implicação importante é que os consumidores devem integrá-lo ao seu próprio sistema de autenticação. O servidor não sabe como identificar um usuário ou espaço de trabalho sem esse JWT.

Claims JWT obrigatórios:

  • sub ou userId
  • workspaceId
  • opcional roles

Exemplo de payload:

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

Por que /oauth/meta/start não é um link público genérico:

  • o servidor precisa saber a qual espaço de trabalho a conta Meta deve ser vinculada
  • esse contexto de espaço de trabalho vem do JWT
  • sem ele, o servidor não pode vincular com segurança o token Meta resultante

Superfície de Ferramentas

Famílias de ferramentas implementadas:

  • Conta e configuração
  • Gerenciamento de campanhas
  • Gerenciamento de conjuntos de anúncios
  • Criativos e anúncios
  • Público e segmentação
  • Relatórios e insights
  • Auxiliares de lote

O servidor atualmente registra 39 ferramentas.

Estrutura do Projeto

  • src/tools definições de ferramentas agrupadas por domínio
  • src/lib auxiliares de autenticação, armazenamento, OAuth, runtime e cliente Meta
  • src/services lógica de serviço Meta específica de domínio
  • src/middleware.ts roteamento OAuth e autenticação JWT do MCP
  • cloudflare-entry.mjs entrada wrapper do Worker para interceptação de rotas específicas do Cloudflare
  • schema.sql esquema D1
  • test testes unitários e de estilo de contrato

Desenvolvimento Local

Instale as dependências:

pnpm install

Execute o desenvolvimento local:

pnpm dev

Scripts úteis:

pnpm build
pnpm test
pnpm deploy

Bindings do Cloudflare

Bindings obrigatórios:

  • Banco de dados D1 vinculado como META_DB
  • Namespace KV vinculado como META_OAUTH_STATE

Segredos obrigatórios:

  • JWT_SECRET ou JWT_JWKS_URL
  • META_APP_ID
  • META_APP_SECRET
  • META_TOKEN_ENCRYPTION_KEY
  • APP_UI_PASSWORD para a página de administração integrada em /app

Configuração opcional:

  • 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

Padrões:

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

Interface de Administração Integrada

O Worker agora inclui uma pequena interface de navegador em /app.

O que ela faz:

  • solicita uma senha de administrador
  • inicia o fluxo OAuth Meta existente sem exigir que você gere manualmente um JWT bearer
  • mostra se uma conta Meta está conectada para o espaço de trabalho de administrador
  • carrega contas de anúncios acessíveis usando a mesma lógica de serviço de get_ad_accounts

Configuração necessária:

  1. Defina APP_UI_PASSWORD no Worker.
  2. Certifique-se de que META_REDIRECT_URI corresponda ao seu host público, por exemplo:
https://meta-mcp.gestalt.xyz/oauth/meta/callback
  1. Abra:
https://meta-mcp.gestalt.xyz/app

Configuração do Aplicativo Meta

No seu aplicativo Meta:

  1. Adicione o produto Marketing API.
  2. Adicione uma plataforma Website.
  3. Defina a URL da plataforma Website para a origem do seu Worker.
  4. Defina App Domains para o domínio do seu Worker.
  5. Defina a URL de callback para:
https://<your-worker-host>/oauth/meta/callback

Se o seu aplicativo usa Facebook Login ou Facebook Login for Business, adicione também essa URL de callback exata às configurações de URI de redirecionamento específicas do produto.

Para um Worker implantado em workers.dev, esses campos geralmente precisam corresponder exatamente ao host do Worker.

Banco de Dados

Aplique o esquema D1:

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

Tabelas:

  • meta_connections
  • meta_ad_accounts_cache

Implantação

Implante o Worker:

pnpm deploy

Após a implantação:

  1. anote a URL pública do Worker
  2. defina META_REDIRECT_URI para https://<your-worker-host>/oauth/meta/callback
  3. atualize o mesmo callback nas configurações do aplicativo Meta

Se você planeja usar um frontend ou painel separado em outra origem, permita essa origem para redirecionamentos de navegador pós-OAuth:

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

Use a origem real do seu frontend em produção.

Fluxo de Teste Manual

1. Gere um JWT de curta duração

Use o mesmo segredo JWT que seu aplicativo usa para o 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
)

2. Inicie o OAuth da Meta

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

Copie o cabeçalho Location para o seu navegador e conclua o fluxo de login da Meta.

Página de sucesso esperada:

Meta account connected.

3. Inicialize o 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. Liste as Ferramentas

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. Chame uma Ferramenta Real

Após o OAuth ser concluído com sucesso, isso deve retornar as contas de anúncios acessíveis para esse espaço de trabalho:

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

Se você receber um erro de conexão/reconexão, o fluxo OAuth e a chamada MCP usaram valores diferentes de workspaceId.

Observações

  • Domínios workers.dev do Cloudflare podem exigir cuidado extra nas configurações do aplicativo Meta.
  • O ponto de entrada do Worker intercepta explicitamente as rotas OAuth antes de delegar ao Worker XMCP gerado.
  • O caminho de build do Cloudflare Worker não é idêntico ao xmcp dev local, então sempre verifique as rotas implantadas após alterações relacionadas ao OAuth.

Referências