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

Related MCP server: facebook-business-mcp

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

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