Meta Ads MCP Server

Servidor MCP em Python para expor dados da Meta Marketing API para clientes compatíveis com MCP.

O que mudou

Esta versão do servidor foi ajustada para execução mais confiável:

• carrega .env automaticamente na raiz do projeto
• falha no boot se META_ACCESS_TOKEN não estiver configurado
• retorna JSON estruturado em todas as tools
• valida date_preset, level e metric antes de chamar a Meta API
• remove erros silenciosos e devolve erros acionáveis para o cliente MCP
• usa streamable-http quando PORT está definido

Requisitos

• Python 3.10+
• token da Meta com permissões compatíveis, como ads_read e read_insights

Instalação

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configuração

Crie um arquivo .env na raiz:

META_ACCESS_TOKEN=EAAB...

Opcionalmente, crie clients.json para apelidos de contas:

{
  "Minha Marca": "act_123456789",
  "Cliente Agencia X": "act_987654321"
}

Também é possível usar CLIENTS_JSON como variável de ambiente com o mesmo conteúdo em JSON.

Execução

Segurança (Public Hosting)

Se você hospedar este servidor publicamente (ex: no Render), é altamente recomendável definir a variável de ambiente MCP_API_KEY.

• No Servidor (Render): Adicione a variável MCP_API_KEY com um valor secreto de sua preferência.
• No Cliente (Ex: Claude Desktop): Adicione o header de autorização na configuração do servidor remoto.

Modo HTTP para deploy (Render)

Quando PORT estiver definido, o servidor usa SSE (Server-Sent Events).

PORT=8000 MCP_API_KEY=seu_segredo_aqui python3 server.py

Quando PORT estiver definido, o servidor usa streamable-http, que é o caminho mais alinhado com o SDK MCP atual para produção.

Exemplo de configuração MCP

{
  "mcpServers": {
    "meta-ads": {
      "command": "/ABSOLUTE/PATH/.venv/bin/python",
      "args": ["/ABSOLUTE/PATH/server.py"],
      "env": {
        "META_ACCESS_TOKEN": "EAAB..."
      }
    }
  }
}

Tools disponíveis

Tool	Função
meta_list_clients	Lista os clientes configurados
meta_get_structure	Lista campanhas ou detalha adsets/ads de uma campanha
meta_get_analytics	Retorna insights estruturados para conta, campanha, adset ou ad
meta_get_ad_creative_details	Retorna dados do criativo de um anúncio
meta_get_account_balance	Retorna saldo, gasto e spend cap da conta
meta_get_demographics	Retorna breakdown por idade/gênero e plataforma
meta_compare_performance	Compara múltiplos IDs
meta_get_trend_chart	Retorna série temporal e gráfico ASCII

Formato de resposta

Todas as tools retornam JSON com este envelope:

{
  "ok": true,
  "data": {}
}

Em caso de erro:

{
  "ok": false,
  "error": {
    "code": "invalid_params",
    "message": "date_preset inválido.",
    "details": {}
  }
}

Problemas comuns

META_ACCESS_TOKEN não definido

• configure a variável de ambiente ou o arquivo .env

ModuleNotFoundError: No module named 'mcp'

• ative o ambiente virtual correto
• rode pip install -r requirements.txt

account_ambiguous

• use o nome exato do cliente em clients.json ou o act_ID

meta_api_error

• valide permissões do token
• confirme se o ID informado pertence à conta/token corretos
• confira limites e rate limits da API da Meta