Meta Ad Library MCP

Servidor MCP de produção para consultar a Meta Ad Library API oficial (/ads_archive) — sem scraping.

Construído com FastMCP, httpx, Pydantic v2 e cache SQLite com TTL (preparado para migrar para Redis).

Ferramentas (v1)

Ferramenta	Descrição
search_meta_ads	Busca anúncios por palavras-chave + país
get_ads_from_page	Lista anúncios de uma página (page_id)
health_check	Verifica token e saúde do servidor

Limitações reais da API (2026)

A Meta Ad Library API é oficial, mas tem restrições importantes:

1. UE e Reino Unido — A API retorna a maior parte dos anúncios comerciais entregues nessas regiões, incluindo dados de transparência (alcance, targeting, beneficiários, etc.).

2. Fora da UE/UK (ex.: EUA, Brasil) — A cobertura de anúncios comerciais é muito limitada. Em geral, a API retorna principalmente:

   • Anúncios de temas sociais, eleições e política (POLITICAL_AND_ISSUE_ADS)
   • Anúncios que atingiram audiência na UE, mesmo que a campanha seja global

3. Sem tradução automática — search_terms devem estar no idioma dos anúncios que você busca.

4. Campos condicionais — spend, impressions, demographic_distribution e similares só aparecem em categorias/regiões específicas (principalmente política e UE).

5. Rate limits — A Graph API aplica limites; o cliente faz retry automático em erros 429/5xx.

6. Não é substituto do site — O site facebook.com/ads/library pode exibir mais anúncios do que a API em alguns cenários fora da UE.

Resumo para agentes de IA: Para pesquisa competitiva comercial no Brasil ou EUA, espere resultados parciais. Para compliance/transparência na UE/UK ou ads políticos globais, a API é confiável.

Pré-requisitos

• Python 3.12+
• Conta Meta for Developers
• User Access Token com permissão ads_read

Como obter o User Access Token

1. Acesse developers.facebook.com e crie um app (tipo Business ou Other).
2. No app, vá em Tools → Graph API Explorer.
3. Selecione seu app e adicione a permissão ads_read.
4. Gere um User Access Token (não Page Token).
5. Para produção, prefira um token de longa duração via Access Token Debugger → Extend Access Token.
6. Copie o token para META_ACCESS_TOKEN.

Documentação oficial: Ad Library API

Setup local

cd meta-ad-library-mcp
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

pip install -r requirements.txt
cp .env.example .env
# Edite .env e defina META_ACCESS_TOKEN

Executar

python server.py

Por padrão usa transporte stdio (ideal para Claude Desktop, Cursor, etc.).

Modo HTTP (remoto / Railway)

# .env
MCP_TRANSPORT=http
MCP_PORT=8000

python server.py
# Endpoint MCP: http://localhost:8000/mcp

Conectar clientes MCP

Cursor

Em Settings → MCP, adicione:

{
  "mcpServers": {
    "meta-ad-library": {
      "command": "python",
      "args": ["D:/caminho/absoluto/para/meta-ad-library-mcp/server.py"],
      "env": {
        "META_ACCESS_TOKEN": "seu_token_aqui"
      }
    }
  }
}

Use o caminho absoluto do server.py e o Python do seu venv se preferir.

Claude Desktop

Em claude_desktop_config.json:

{
  "mcpServers": {
    "meta-ad-library": {
      "command": "python",
      "args": ["/caminho/absoluto/para/meta-ad-library-mcp/server.py"],
      "env": {
        "META_ACCESS_TOKEN": "seu_token_aqui"
      }
    }
  }
}

Cliente HTTP (Ollama, scripts, etc.)

Com MCP_TRANSPORT=http:

import asyncio
from fastmcp import Client

async def main():
    async with Client("http://localhost:8000/mcp") as client:
        result = await client.call_tool(
            "search_meta_ads",
            {"search_terms": "fitness", "country": "GB", "limit": 10},
        )
        print(result)

asyncio.run(main())

Deploy no Railway

1. Preparar o repositório

Faça push desta pasta para um repositório Git (GitHub, GitLab, etc.).

2. Criar projeto no Railway

1. railway.app → New Project → Deploy from GitHub repo
2. Selecione o repositório

3. Variáveis de ambiente

Variável	Valor
META_ACCESS_TOKEN	Seu token Meta
MCP_TRANSPORT	http
MCP_HOST	0.0.0.0
MCP_PORT	${{PORT}} (Railway injeta a porta)
CACHE_DB_PATH	/data/cache.db

4. Volume persistente (cache SQLite)

1. No serviço Railway → Volumes → Add Volume
2. Mount path: /data
3. Garanta CACHE_DB_PATH=/data/cache.db

Sem volume, o cache é perdido a cada redeploy.

5. Dockerfile

O projeto já inclui um Dockerfile otimizado. Railway detecta e usa automaticamente.

6. Verificar deploy

curl https://seu-app.up.railway.app/mcp

Use a URL pública no cliente MCP com transporte HTTP.

Variáveis de ambiente

Variável	Padrão	Descrição
META_ACCESS_TOKEN	—	Obrigatório. Token com ads_read
META_API_VERSION	v25.0	Versão da Graph API
CACHE_TTL_SECONDS	3600	TTL do cache em segundos
CACHE_DB_PATH	./data/cache.db	Caminho do SQLite
MCP_TRANSPORT	stdio	stdio ou http
MCP_HOST	0.0.0.0	Host HTTP
MCP_PORT	8000	Porta HTTP
LOG_LEVEL	INFO	Nível de log
REQUEST_TIMEOUT_SECONDS	30	Timeout httpx
MAX_RETRIES	3	Retries em 429/5xx

Estrutura do projeto

meta-ad-library-mcp/
├── server.py                 # FastMCP server + tools
├── config.py                 # Settings via env vars
├── clients/
│   └── meta_api_client.py    # httpx client + pagination/errors
├── models/
│   └── ad_models.py          # Pydantic v2 models
├── cache/
│   ├── base.py               # CacheBackend protocol (Redis-ready)
│   └── sqlite_cache.py       # SQLite implementation
├── data/                     # SQLite cache (gitignored)
├── requirements.txt
├── Dockerfile
└── README.md

Migrar cache para Redis

Implemente CacheBackend em cache/redis_cache.py com os mesmos métodos de SqliteCache, injete no MetaApiClient em server.py, e troque a instância — nenhuma tool precisa mudar.

Exemplos de uso (tools)

Busca por keyword (Reino Unido — boa cobertura comercial):

{
  "search_terms": "protein powder",
  "country": "GB",
  "limit": 25
}

Anúncios de uma página:

{
  "page_id": "123456789012345",
  "country": "US",
  "ad_active_status": "ALL",
  "limit": 50
}

Paginação:

Passe after com o valor de paging.next_cursor da resposta anterior.

Licença

MIT — use livremente em projetos pessoais e comerciais.