# 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](LICENSE); dependências conservam suas [próprias licenças](THIRD_PARTY_NOTICES.md). 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.

```sh
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](docs/META_DEVELOPER.md): 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](docs/EXECUCAO.md).

## Executar

```sh
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:

```json
{
  "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](docs/EXECUCAO.md).

## Verificar

```sh
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](docs/FERRAMENTAS.md), [resultados/limites](docs/VALIDACAO.md) e [sanitização](docs/SANITIZACAO.md).

## 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](docs/REVISAO_PUBLICACAO.md) 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](docs/EXECUCAO.md), 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](docs/CLOUDFLARE.md).