MCP Facebook Ads (Python)

Servidor MCP em Python para consultar dados da Facebook Marketing API (somente leitura). Baseado no projeto mcp-facebook-ads, porém construído com Python e pronto para publicação no PyPI.

🚀 Recursos

• Consultar campanhas da conta de anúncios (get_campaigns)
• Consultar métricas de campanhas (get_campaign_insights)
• Consultar insights da conta (get_account_insights)
• Consultar criativos de anúncios (get_ad_creatives)
• Listar anúncios de uma campanha (get_campaign_ads)

📋 Pré-requisitos

• Python 3.10+
• Conta e App configurados no Facebook Developers
• Access Token com permissão ads_read
• ID da conta de anúncios

🔧 Instalação (local)

pip install -e .

Opcionalmente, copie .env.example para .env e configure as credenciais:

FB_ACCESS_TOKEN=seu_token_aqui
FB_ACCOUNT_ID=seu_account_id_aqui
FB_API_VERSION=v21.0

🎯 Como usar

Via PyPI + npx-like (uvx/pipx/python -m)

Após a publicação no PyPI será possível executar:

pip install mcp_facebook_ads
mcp_facebook_ads --transport stdio

Para integrar ao MCP config (por exemplo .cursor/mcp.json):

"facebook-ads": {
  "command": "mcp_facebook_ads",
  "args": ["--transport", "stdio"],
  "env": {
    "FB_ACCESS_TOKEN": "seu_token_aqui",
    "FB_ACCOUNT_ID": "seu_account_id_aqui",
    "FB_API_VERSION": "v21.0"
  }
}

Execução local direta

python -m mcp_facebook_ads --transport stdio

Variáveis de ambiente

🧰 Tools

As mesmas tools do projeto em Node, com os mesmos parâmetros e comportamento. Use os nomes: get_campaigns, get_campaign_insights, get_account_insights, get_ad_creatives, get_campaign_ads.

📦 Publicação no PyPI

O projeto já possui pyproject.toml configurado com hatchling. Para publicar:

python -m build
python -m twine upload dist/*

📝 License

MIT