meta-business-insights-mcp

Servidor MCP para o Claude Desktop ler dados do Meta Business (Facebook Pages e Instagram) via Graph API, com agregação cross-account do portfólio.

Complementa o MCP de Meta Ads: lá você vê o que veio de campanha; aqui você vê o número real da conta — inclusive o crescimento orgânico.

O que dá para perguntar

• "Quantos seguidores o portfólio inteiro ganhou por mês em 2026?"

• "Compare o crescimento de seguidores do Instagram entre as 5 contas maiores."

• "Qual página teve mais visitas de perfil no último trimestre?"

• "Mostre alcance e interações por mês, consolidado, com variação mês a mês."

Related MCP server: meta-ads-mcp

Instalação

npm install
npm run build

Crie o .env a partir do exemplo e preencha o token:

cp .env.example .env

Permissões necessárias no token

pages_read_engagement, pages_show_list, read_insights, instagram_basic, instagram_manage_insights e business_management.

Valide tudo antes de plugar no Claude:

npm run probe

O probe imprime o portfólio descoberto, avisa quais páginas estão sem Page Access Token e puxa 4 meses de seguidores como amostra.

Dois modos de execução

O servidor MCP é o mesmo nos dois — muda só quem o serve.

Configuração no Claude Desktop (modo stdio)

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "meta-business-insights": {
      "command": "node",
      "args": ["/caminho/para/meta-business-insights-mcp/dist/index.js"],
      "env": {
        "META_ACCESS_TOKEN": "SEU_TOKEN",
        "META_BUSINESS_ID": "SEU_BUSINESS_ID"
      }
    }
  }
}

Reinicie o Claude Desktop depois de salvar.

Servidor compartilhado numa VPS (modo HTTP)

O ganho não é performance: é que o token do Meta fica só na VPS. Distribuir o .env para cada pessoa colocaria um token com acesso de escrita ao portfólio inteiro em N notebooks, sem forma de revogar um sem revogar todos.

1. Tokens da equipe

Um bearer por pessoa, não um compartilhado. Custa o mesmo e permite tirar alguém removendo uma linha:

openssl rand -hex 32   # repita por pessoa

MCP_HTTP_TOKENS=ana:3f9c…,bruno:a71d…,carla:88e2…

O nome antes do : só serve para o log — cada linha do journal diz quem consultou. O servidor se recusa a subir com MCP_HTTP_TOKENS vazio, para que ninguém exponha o portfólio por esquecimento.

2. Na VPS

Conta de sistema sem login e sem home — o useradd do shadow-utils funciona tanto em Debian/Ubuntu quanto em RHEL/Alma/Rocky, ao contrário do adduser, que tem sintaxes diferentes em cada família:

useradd --system --user-group --shell /usr/sbin/nologin --no-create-home mcp
git clone <repo> /opt/meta-business-insights-mcp
cd /opt/meta-business-insights-mcp
npm ci && npm run build
chown -R mcp:mcp /opt/meta-business-insights-mcp

O .env não vai para a VPS. As variáveis ficam em /etc/meta-mcp.env (dono root, modo 0600), que o systemd lê:

install -m 600 /dev/null /etc/meta-mcp.env
$EDITOR /etc/meta-mcp.env     # META_ACCESS_TOKEN, META_BUSINESS_ID,
                              # MCP_HTTP_TOKENS, META_DATA_DIR=/var/lib/meta-mcp
cp deploy/meta-mcp.service /etc/systemd/system/
systemctl daemon-reload && systemctl enable --now meta-mcp
journalctl -u meta-mcp -f

3. TLS

Aponte um subdomínio para o IP da VPS, ajuste o host no deploy/Caddyfile e copie para /etc/caddy/Caddyfile. O Caddy emite o certificado sozinho.

O flush_interval -1 no proxy não é detalhe: sem ele o Caddy segura os eventos SSE até o fim do stream, e consultas longas — o Meta demora vários segundos — parecem travadas no Claude.

O processo escuta em 127.0.0.1. Não abra a porta 8787 no firewall: sem TLS o bearer viajaria em texto claro.

Teste antes de plugar no Claude:

curl https://mcp.exemplo.com/healthz
curl -X POST https://mcp.exemplo.com/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

4. Conectar o Claude Desktop de cada pessoa

Duas formas, porque a interface de conectores do Claude só tem campos de OAuth — não há campo para um bearer fixo.

a) Conector personalizado com static_headers. É o caminho limpo: o Owner da organização adiciona o conector uma vez em Configurações da organização, com o header, e cada pessoa só habilita. Só que static_headers está em beta e o credencial é único para a organização inteira — o que anula os tokens por pessoa. Confira se sua conta tem a opção antes de contar com ela.

b) Ponte local stdio→HTTP. Funciona hoje, em qualquer plano, e preserva um token por pessoa. Cada uma põe no próprio claude_desktop_config.json:

{
  "mcpServers": {
    "meta-business-insights": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.exemplo.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer SEU_TOKEN_PESSOAL"
      }
    }
  }
}

O Authorization:${AUTH_HEADER} sem espaço depois do : é intencional: o Claude Desktop no Windows não escapa espaços dentro de args ao chamar o npx, e o header chega quebrado. O espaço vai dentro da variável.

O que essa forma não dá: acesso pelo claude.ai ou pelo app de celular — a ponte roda na máquina de cada pessoa. Se isso for necessário, o caminho é (a) ou implementar OAuth.

O que um bearer fixo não resolve

Vale ter explícito, porque é fácil descobrir tarde:

• Sem consentimento por pessoa. Quem tem o token tem tudo que as 9 tools fazem, incluindo graph_api_get.

• Revogação é manual. Sai alguém → editar /etc/meta-mcp.env e systemctl restart meta-mcp.

• O token não expira sozinho. Vale trocar periodicamente.

• Nunca coloque o token na URL (?token=…). A especificação do MCP proíbe, e URLs vazam em log de proxy, histórico e referrer. É por isso que aqui ele vai no header.

Tools

Todas as tools de dados aceitam assets (IDs, nomes de Página ou @usuario), since/until e granularity. Deixar assets vazio significa portfólio inteiro.

Como os números de seguidores são obtidos

Essa é a parte que exige atenção ao ler os relatórios.

Facebook. A métrica page_follows é um snapshot diário do total acumulado, então o total no fim de cada período vem direto da API (coluna "Fonte do total" = API). Ganhos e perdas vêm de page_daily_follows_unique e page_daily_unfollows_unique.

Instagram. Não existe métrica de total acumulado. A API só informa quantos seguidores entraram e saíram em cada janela (follows_and_unfollows). O total histórico é reconstruído de trás para frente a partir do followers_count atual — por isso a série é sempre buscada até hoje, mesmo quando você pede um intervalo que termina no passado, e a coluna "Fonte do total" mostra estimado.

O breakdown follow_type dessa métrica nomeia o estado resultante da transição, não quem executou a ação:

Isso contraria o que várias fontes de terceiros afirmam (que NON_FOLLOWER seriam os novos seguidores). Duas verificações independentes concordam:

1. A soma de FOLLOWER bate exatamente com a soma de follower_count — que é bruto, nunca negativo em nenhum dos 30 dias medidos — nas três contas testadas.

2. Numa conta do portfólio, a soma de FOLLOWER de jan a jul/2026 deu 5.369 — exatamente o número que o Business Suite reporta como seguidores ganhos no período.

Cuidado ao mexer em classifyFollowType: casar por substring quebra, porque NON_FOLLOWER também contém FOLLOWER.

O Business Suite reporta ganhos brutos. No mesmo período acima, 4.208 contas deixaram de seguir, então o crescimento líquido foi de +1.161 — não 5.369. Ao comparar os relatórios deste servidor com a interface do Meta, compare a coluna "Ganhos", não o "Saldo".

Consequência prática: se a conta ficou fora do ar para a API em algum período, a reconstrução para no primeiro buraco e devolve — dali para trás, em vez de inventar um número.

Snapshots locais. follower_count do Instagram só volta 30 dias e Page Insights guarda ~2 anos. Rodando save_followers_snapshot periodicamente (um cron, ou um /loop no Claude Code), o portfólio acumula um histórico próprio que não depende da janela do Meta nem das deprecações de métrica.

Métricas descontinuadas

O Meta desligou page_fans e toda a família impressions em 15/11/2025, e outra leva cai em 15/06/2026. O catálogo em src/metrics.ts mapeia antiga → substituta (page_fans → page_follows, page_impressions → page_media_view, impressions do Instagram → views), e as tools avisam quando você pede uma métrica morta em vez de devolver um erro #100 sem contexto.

Limites da Graph API já tratados

Tudo abaixo foi verificado contra a API real na v26, não só lido na documentação.

• Page Access Token. Page e Instagram Insights recusam o token do System User com (#190). Os tokens de cada Página são resolvidos uma vez e cacheados por 10 minutos. No batch, o token por operação precisa ir na query string do relative_url — como campo do objeto da operação o Meta ignora silenciosamente.

• end_time tem significados opostos nas duas superfícies. Pedindo a mesma janela (01/07 a 10/07) nas duas: o Facebook devolve end_time de 02/07 a 11/07 (é o limite da janela, o dia medido é end_time - 1); o Instagram devolve de 01/07 a 10/07 (já é o dia medido). Aplicar o mesmo deslocamento nos dois faz valores vazarem para o mês anterior.

• Quase toda métrica do Instagram é total_value-only. Só reach e follower_count aceitam time_series; as demais devolvem um único número por janela. Por isso as consultas do Instagram fazem uma chamada por período do relatório — se a janela cruzasse a fronteira do mês, o valor inteiro cairia em um só lado. Consultas que exigiriam mais de 600 chamadas são recusadas com uma mensagem explicando como reduzir o recorte.

• Janela máxima por request: 93 dias em Page Insights, 30 dias no Instagram ((#100) There cannot be more than 30 days between since and until). As consultas são fatiadas e recombinadas automaticamente.

• Uma métrica inválida não derruba as outras. Se um request com várias métricas falha, o servidor refaz aquela janela métrica a métrica: as válidas retornam normalmente e a inválida vira aviso.

• Requests são agrupados em batches de 50 — o erro de uma conta não afeta as demais.

• Rate limit (códigos 4, 17, 32, 613, 80000+) tem retry com backoff exponencial.

• Os dados dos últimos ~2 dias costumam voltar zerados: é a latência de consolidação do próprio Meta, não uma falha do servidor.