Facebook Ads

Servidor MCP do Facebook/Meta Ads

Este projeto fornece um servidor MCP que atua como interface para o Meta Ads, permitindo acesso programático aos dados e recursos de gerenciamento do Meta Ads.

claude_demo.mp4

Configuração Fácil com Um Clique

Para uma experiência de configuração mais simples, oferecemos instaladores prontos para uso:

👉 Baixar instalador - https://gomarble.ai/mcp

Junte-se à nossa comunidade para obter ajuda e atualizações

👉 Comunidade Slack - AI in Ads

Experimente também o servidor MCP do Google Ads

👉 Google Ads MCP - Google Ads MCP

O Que Ele Faz

• Instala e configura o servidor MCP localmente
• Gerencia automaticamente a configuração do ambiente
• Solicita autenticação por token do Meta durante o processo, o que é opcional
• Se o token de acesso do Meta não for fornecido, conecta-se ao servidor da GoMarble para criar o token em seu nome

Aviso Importante

Esta configuração não exige que você obtenha manualmente um Token de Acesso de Desenvolvedor do Meta.

Em vez disso, ela se conecta com segurança ao servidor da GoMarble para criar o token em seu nome. A GoMarble não armazena seu token — ele é salvo localmente na sua máquina para uso com o servidor MCP.

---

Configuração

Pré-requisitos

• Python 3.10+
• Dependências listadas em requirements.txt

1. (Opcional, mas Recomendado) Criar e Ativar um Ambiente Virtual:

   python3 -m venv venv
   source venv/bin/activate  # On Windows use \`venv\Scripts\activate\`
   

   Usar um ambiente virtual ajuda a gerenciar as dependências do projeto de forma limpa [Fonte].
2. Instalar Dependências:

   pip install -r requirements.txt
   

3. Obter Token de Acesso do Meta: Obtenha um Token de Acesso de Usuário do Meta com as permissões necessárias (ex.: ads_read). Você pode gerá-lo pelo portal de desenvolvedores do Meta. Siga este link.

Uso com Clientes MCP (ex.: Cursor, Claude Desktop)

Para integrar este servidor a um cliente compatível com MCP, adicione uma configuração (Claude) semelhante à seguinte. Substitua YOUR_META_ACCESS_TOKEN pelo seu token real e ajuste o caminho para server.py se necessário.

{
  "mcpServers": {
    "fb-ads-mcp-server": {
      "command": "python",
      "args": [
        "/path/to/your/fb-ads-mcp-server/server.py",
        "--fb-token",
        "YOUR_META_ACCESS_TOKEN"
      ]
      // If using a virtual environment, you might need to specify the python executable within the venv:
      // "command": "/path/to/your/fb-ads-mcp-server/venv/bin/python",
      // "args": [
      //   "/path/to/your/fb-ads-mcp-server/server.py",
      //   "--fb-token",
      //   "YOUR_META_ACCESS_TOKEN"
      // ]
    }
  }
}

Reinicie o aplicativo do cliente MCP após fazer a atualização na configuração.

(Observação: No Windows, talvez seja necessário ajustar a estrutura do comando ou usar cmd /k dependendo da sua configuração.)

Depuração do Servidor

Execute server.py, fornecendo o token de acesso pelo argumento --fb-token.

python server.py --fb-token YOUR_META_ACCESS_TOKEN

Ferramentas MCP Disponíveis

Este servidor MCP fornece ferramentas para interagir com objetos e dados do META Ads:

Nome da Ferramenta	Descrição
Leitura de Conta e Objeto
list_ad_accounts	Lista as contas de anúncios vinculadas ao token.
get_details_of_ad_account	Recupera detalhes de uma conta de anúncios específica.
get_campaign_by_id	Recupera detalhes de uma campanha específica.
get_adset_by_id	Recupera detalhes de um conjunto de anúncios específico.
get_ad_by_id	Recupera detalhes de um anúncio específico.
get_ad_creative_by_id	Recupera detalhes de um criativo de anúncio específico.
get_adsets_by_ids	Recupera detalhes de vários conjuntos de anúncios pelos seus IDs.
Busca de Coleções
get_campaigns_by_adaccount	Recupera campanhas dentro de uma conta de anúncios.
get_adsets_by_adaccount	Recupera conjuntos de anúncios dentro de uma conta de anúncios.
get_ads_by_adaccount	Recupera anúncios dentro de uma conta de anúncios.
get_adsets_by_campaign	Recupera conjuntos de anúncios dentro de uma campanha.
get_ads_by_campaign	Recupera anúncios dentro de uma campanha.
get_ads_by_adset	Recupera anúncios dentro de um conjunto de anúncios.
get_ad_creatives_by_ad_id	Recupera criativos associados a um anúncio.
Insights e Dados de Desempenho
get_adaccount_insights	Recupera insights de desempenho de uma conta de anúncios.
get_campaign_insights	Recupera insights de desempenho de uma campanha.
get_adset_insights	Recupera insights de desempenho de um conjunto de anúncios.
get_ad_insights	Recupera insights de desempenho de um anúncio.
fetch_pagination_url	Busca dados de uma URL de paginação (ex.: de insights).
Histórico de Atividades/Alterações
get_activities_by_adaccount	Recupera o histórico de alterações de uma conta de anúncios.
get_activities_by_adset	Recupera o histórico de alterações de um conjunto de anúncios.

(Observação: A maioria das ferramentas suporta parâmetros adicionais como fields, filtering, limit, paginação, intervalos de datas, etc. Consulte as docstrings detalhadas em server.py para a lista completa e descrição dos argumentos de cada ferramenta.)

(Observação: Se o seu token de acesso do Meta expirar, você precisará gerar um novo e atualizar o arquivo de configuração do cliente MCP com o novo token para continuar usando as ferramentas.)

Dependências

• mcp (>=1.6.0)
• requests (>=2.32.3)

Licença

Este projeto é licenciado sob a Licença MIT.

---

Instalação via Smithery

Para instalar o Facebook Ads Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @gomarble-ai/facebook-ads-mcp-server --client claude