mcp-1nort-meta

Servidor MCP que expõe a Meta Marketing API ao Claude: relatórios de desempenho de anúncios e ajustes operacionais (pausar/reativar, alterar orçamento), para as contas dos clientes da 1nort.

Roda local, por stdio, em TypeScript sobre Node 20+.

O token configurado é de produção. Ele é de um usuário de sistema do Business Manager e alcança as contas de todos os clientes da agência. A allowlist de contas é o que restringe este servidor a um subconjunto — leia docs/seguranca-mutacoes.md antes de liberar escrita.

Começando

npm ci
cp .env.example .env      # e preencha
npm run check             # typecheck + testes
npm run build

O .env precisa ter META_AD_ACCOUNT_ALLOWLIST preenchida. Sem ela o servidor não inicia — de propósito: vazio nunca significa "liberar todas as contas".

Rodar e inspecionar

npm run inspector    # abre o MCP Inspector apontando para o servidor
npm run dev          # roda direto do TypeScript, sem build
npm start            # roda o build de dist/

Registrar no Claude Code

O .mcp.json na raiz já registra dois servidores (só caminhos, nenhum segredo):

• meta-ads — respeita o .env.

• meta-ads-somente-leitura — força META_READ_ONLY=true. Como o ambiente do processo tem precedência sobre o --env-file, este é somente-leitura por construção, independente do que o .env diga. Use este como padrão e deixe o outro para sessões deliberadas de alteração.

Ou pela linha de comando:

claude mcp add --scope project meta-ads -- node --env-file=.env dist/index.js

No Claude Desktop, o claude_desktop_config.json precisa de caminhos absolutos (Desktop não tem raiz de projeto).

Related MCP server: Marketing MCP

Ferramentas

Leitura (sempre disponíveis)

Banco (só com DB_FERRAMENTAS_MCP=true)

Leem o banco da 1nort com um usuário SELECT-only. Histórico já coletado, sem consumir cota da Meta.

Nenhuma delas aceita SQL, e nenhuma aceita e-mail. SQL livre não tem como ser seguro aqui: o usuário somente-leitura enxerga tb_credenciais (com token_kommo, token_ghl, pixel_token) e a própria tb_meta_ads tem pixel_token; um agente que lê nome de campanha escrito por cliente é superfície de injeção. Filtrar SQL na aplicação não resolve (CTE, subquery, pg_catalog, ::regclass), e a restrição correta — REVOKE no Postgres — depende de um direito que não temos. E como nenhuma ferramenta aceita e-mail, o modelo não consegue trocar o próprio escopo: isso é ação do humano na tela.

Escrita (só com META_READ_ONLY=false)

E três de leitura que existem para o modelo não inventar id: meta_list_creatives, meta_list_publications e meta_list_audiences.

Tudo nasce pausado, e isso não é parâmetro. Nenhuma ferramenta de criação aceita status: um objeto pausado não gasta, então errar custa zero, e ativar continua sendo meta_update_status — auditado e com confirmação do host.

special_ad_categories é constante [], fora do schema. A 1nort declara que não anuncia crédito, emprego, moradia nem tema social. Se isso mudar — financiamento solar seria CREDIT —, o valor está em SEM_CATEGORIA_ESPECIAL, num lugar só, e alterá-lo é decisão de um humano. Declarar categoria especial errada é violação de política da Meta, não erro de campanha.

Não existe exclusão nem arquivamento. DELETED e ARCHIVED não estão no schema, então não há caminho de código que chegue a eles — objeto criado por engano se apaga à mão no Gerenciador.

Duas regras de negócio que não podem ser afrouxadas

1. Leads de formulário e de mensagem nunca se somam.

leads_form     ← onsite_conversion.lead_grouped
leads_message  ← onsite_conversion.messaging_conversation_started_7d

O action type genérico lead é ignorado — conta formulário por outro critério e diverge de lead_grouped por ordem de grandeza. Ausência devolve null, nunca 0: "não medido" e "medido e deu zero" são fatos diferentes. Regra portada de ExtratorAcoesMeta.java, do projeto Citrino, para que os relatórios dos dois sistemas não divirjam para o mesmo cliente no mesmo dia.

2. Orçamento é informado na unidade MAIOR da moeda.

amount: 250.50 significa R$ 250,50. A Meta armazena em unidade menor (25050) e a conversão é do servidor. Mandar centavos aqui definiria um orçamento cem vezes maior — por isso a resposta sempre mostra as duas unidades lado a lado, para o erro saltar aos olhos antes da confirmação.

Segurança

Resumo; o contrato completo está em docs/seguranca-mutacoes.md.

• Allowlist de contas, com comparação exata e tipo branded que o compilador cobra.

• Vínculo objeto → conta antes de toda escrita: POST /{id} não menciona conta nenhuma, então sem essa releitura a allowlist não valeria nada na escrita.

• Duas chaves para aplicar: META_WRITE_DRY_RUN=false e confirm: true. Prévia e aplicação percorrem o mesmo código; muda só o validate_only, que é validado pela própria Meta.

• Limites de orçamento com falha fechada; moeda fora da tabela é recusada, nunca chutada.

• Auditoria de toda tentativa, inclusive recusas, em stderr.

• Token só no header Authorization; appsecret_proof em toda chamada.

Variáveis de ambiente

Ver .env.example. As que mais importam:

Interface local

npm run ui         # constrói tudo e sobe em http://127.0.0.1:8787

Ou, do Claude Code: /painel — ou /painel email@do-usuario para abrir já escopado.

O painel lê do banco: uma consulta traz o histórico de todas as contas do escopo. Um gestor com 67 contas carrega em menos de 2 s com zero chamadas à Meta. O que só a Graph sabe — teto de gastos, status da conta, moeda, fuso, campanhas ativas — chega ao expandir uma linha, uma conta por vez. Antes eram quatro chamadas por conta na carga da tela, o que a 67 contas seriam 268 chamadas contra um limite de ~15/min.

O chat responde interpretando os números, com as duas famílias de ferramenta. A conversa é gravada em .conversas/ (fora do git): sobrevive a trocar de aba, a F5, a fechar o navegador e a reiniciar o servidor. Uma resposta cortada no meio volta marcada como interrompida — e nunca é retomada sozinha, o que recobraria tokens e poderia reexecutar consultas.

Escopo por usuário

Ativar um e-mail resolve users → tb_usuarios_clientes → tb_clientes → tb_meta_ads e constrói uma Allowlist nova com essas contas. ROLE_ADMINo usuário somente-leitura enxerga todos os clientes ativos, porque a plataforma não enumera vínculo de administrador. Contas sem cliente vinculado não entram no escopo de ninguém — conta sem dono não é de todo mundo —, mas a contagem aparece no aviso.

Ativar é ação de operador, pelo controle da tela ou por ?ativar=. Não é um padrão que o sistema reconheça dentro de uma mensagem: o agente lê texto escrito por cliente, e uma campanha chamada [ativar:alguem@1nort...] viraria escalonamento de escopo por um campo que o cliente controla. O atalho de digitação existe, mas é tratado só no navegador e removido antes do envio.

De onde vem cada número

A escolha da tabela foi medida, não suposta (npm run diag:comparar). Em julho/2026, contra a Graph: tb_dados_trafego perdia 67 leads de mensagem numa conta, 54 de formulário noutra, e não tinha linha nenhuma para uma terceira que gastou R$ 4.850 no mês. tb_meta_anuncios_metricas bateu nas três, dentro de 0,2%, e ainda preserva NULL para "não medido" — coisa que o agregado legado não faz (13.264 linhas, 8.875 zeros onde deveria haver nulo).

Período pedido além da cobertura é recortado e avisado, nunca completado em silêncio: somar um dia do banco com um dia da Graph produz um total que não reconcilia com fonte nenhuma.

Desenvolvimento

npm test           # 325 testes
npm run typecheck
npm run fmt
npm run diag:banco     # sonda o banco: cobertura, semântica de nulo, escopo de um e-mail
npm run diag:comparar -- act_123 2026-07-01 2026-07-31   # banco × Graph, mesma conta e período

Testes injetam fetch em vez de mockar o cliente Graph, então exercitam o que de fato quebra: montagem de URL, a string fields, encoding do time_range, cursor de paginação e parsing de número-string. test/invariantes.test.ts varre todas as URLs emitidas atrás do token, confere que ele está no Authorization de toda chamada, e falha se alguma coisa escrever em stdout.

Pendências conhecidas

1. Conferir os números contra o Gerenciador de Anúncios antes de confiar neles. A Meta interpreta datas no fuso da conta, e a janela de atribuição padrão molda a contagem de leads. Toda resposta de meta_get_insights traz account_timezone e o período resolvido justamente para permitir essa conferência. Pode ser necessário fixar action_attribution_windows explicitamente.

2. Criar uma campanha sacrificial antes do primeiro teste de escrita real — campanha nova, pausada, orçamento mínimo, sem anúncios. Senão a primeira escrita cai num cliente pagante.

3. Ligar Require App Secret nas configurações do app Meta. O appsecret_proof já é enviado em toda chamada, mas o benefício (token roubado deixa de servir sozinho) só vale depois de ativar a exigência do lado da Meta.

4. Token com escopo menor. A allowlist é controle de aplicação sobre uma credencial sem limite técnico. A correção estrutural é um segundo usuário de sistema do BM com acesso só às contas permitidas.

5. v21.0 expira em 2027-01-21. Agendar o bump, de preferência junto com o Citrino, para o conhecimento compartilhado de erros e action types continuar valendo.

6. Rate limit (~15 req/min por conta). Há teto de páginas e de linhas, e o resultado sempre informa truncated. Falta decidir se vale acrescentar pausa entre páginas.

7. node_modules/ e dist/ dentro do OneDrive sofrem varredura de sincronização contínua. Recomendo excluir os dois do sync, ou mover o projeto para fora do OneDrive.

8. O agregado tb_dados_trafego está errado onde tb_meta_anuncios_metricas está certo. Vale investigar o coletor ou aposentar a tabela — hoje ela só alimenta vw_desempenho_conta_diario, que também expõe um total_leads somado e deveria sair de cena junto. Ver docs/proposta-tabelas.sql.

9. .conversas/ dentro do OneDrive significa transcript com dado de cliente (gasto, nome de campanha, id de conta) sincronizando para uma nuvem pessoal. Mesmo problema do item 7, com conteúdo mais sensível.

10. Postgres de produção sem TLS na internet pública. A senha e todas as linhas viajam em texto claro. Não é bug deste projeto, mas vale levar a quem cuida do db02.