MCP Meta Ads

MCP em português para Facebook/Instagram Ads: consultas, diagnósticos, campanhas, públicos, formulários e criativos. Mantém 62 ferramentas principais, 5 prompts, 1 resource + 2 resource templates e 3 ferramentas auxiliares de mídia local. Perfil completo por padrão; ?profile=guided mantém as 33 ferramentas desse perfil.

Código de Daniel Kyochi Michigami sob MIT; dependências conservam suas próprias licenças. Nome sugerido: meta-ads-mcp.

Instalar

Use Node 22 (validado) e pnpm 11.17.0. MongoDB mantém sessões, auditoria e idempotência; SQLite guarda OAuth/jobs. FFmpeg/ffprobe são necessários para mídia. ElevenLabs é opcional para narração e pode cobrar pelo uso.

corepack enable
corepack prepare pnpm@11.17.0 --activate
pnpm install --frozen-lockfile
cp .env.example apps/mcp-server/.env
pnpm build

Configure seu próprio app e suas próprias credenciais Meta no .env privado. Para stdio, use META_ACCESS_TOKEN ou App ID/Secret para OAuth. Para HTTP, configure App ID/Secret, PUBLIC_URL e callback /callback. Siga o guia Meta Developer: tokens, papéis, Development/Live, Standard/Advanced Access e revisão. A Meta não concede aprovação automaticamente.

Configure MONGODB_URI para um banco novo. Os defaults de token, MongoDB e configuração Codex são separados da instalação original; sem credenciais, chamadas falham claramente. Detalhes: execução/configuração.

Related MCP server: ,

Executar

pnpm start         # HTTP: porta 3000, conectar em /auth, MCP em /mcp
pnpm start:stdio   # Ou processo stdio para seu cliente MCP

Exemplo fictício de cliente stdio:

{
  "mcpServers": {
    "meta-ads": {
      "command": "node",
      "args": ["/caminho/mcp/apps/mcp-server/dist/server.js"],
      "env": { "META_ACCESS_TOKEN": "<seu-token-privado>" }
    }
  }
}

Pedidos fictícios: “Liste as campanhas da conta de teste”; “Prepare uma campanha de alcance, sem criar nada”; “Analise os últimos 7 dias”; “Mostre os criativos em execução”. Criações/edições/exclusões reais exigem autorização explícita; o perfil guiado também permite escrita.

Mídia local usa um segundo processo, dist/localMediaServer.js, com MCP_DANI_MEDIA_DIR, MCP_DANI_URL e MCP_DANI_SESSION_ID próprios. Configuração do auxiliar.

Verificar

pnpm build
pnpm typecheck
pnpm test
pnpm test:local-media

Testes usam mocks/fixtures, HOME isolado e bloqueio de rede externa. Inventário e schemas, resultados/limites e sanitização.

Segurança e problemas comuns

Use HTTPS, proteja bancos/tokens/backups e conceda apenas acesso Meta necessário. Tokens, dados de clientes e .env nunca entram no código. Revise os riscos herdados antes de abrir acesso público.

• Sem token: configure credenciais próprias e callback correto.

• Meta 10/200: confira papéis, escopos e acesso à Página/conta.

• Campanha incompleta: confira MongoDB; mantenha operation_key e reconcilie IDs antes de repetir.

• Vídeo falha: confira FFmpeg/ffprobe, DATA_DIR e ElevenLabs quando utilizado.

• Upload 401/403: confira a sessão MCP, distinta do token Meta.

VPS e Cloudflare

Guia local/VPS/Docker, somente instruções; nenhum deploy foi feito. Use Streamable HTTP: SSE herdado tem uma falha de contexto do token. Cloudflare Tunnel/Node é alternativa ainda não testada; Workers não preserva todas as capacidades atuais. Limites e fontes oficiais.