# 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

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

## Configuração

Crie um arquivo `.env` na raiz:

```bash
META_ACCESS_TOKEN=EAAB...
```

Opcionalmente, crie `clients.json` para apelidos de contas:

```json
{
  "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).

```bash
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

```json
{
  "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:

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

Em caso de erro:

```json
{
  "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