Facebook Ads Library

Obtenha qualquer resposta da Facebook Ads Library, realize pesquis

Documentação

Servidor MCP da Biblioteca de Anúncios do Facebook

Este é um servidor Model Context Protocol (MCP) para a Biblioteca de Anúncios do Facebook.

Com ele, você pode pesquisar a biblioteca pública de anúncios do Facebook para qualquer empresa ou marca, ver o que elas estão veiculando atualmente e analisar suas campanhas publicitárias. Você pode analisar imagens/textos de anúncios, analisar anúncios em vídeo com insights abrangentes, comparar estratégias de empresas e obter insights sobre o que está funcionando nas campanhas delas.

Aqui está um exemplo do que você pode fazer quando ele está conectado ao Claude.

MCP.demo.mp4

A maneira mais fácil de usar o MCP da Biblioteca de Anúncios do Facebook é a versão hospedada da Proxy (useproxy.dev). Sem chaves de API, sem chave Gemini, sem Python, sem servidor para executar — basta conectar e começar a consultar.

⚡ Zero configuração — nada para instalar, configurar ou manter
🔑 Sem chaves de API — pule as chaves ScrapeCreators e Gemini completamente
🔌 Funciona em qualquer lugar — ChatGPT, Claude, Cursor, Manus e qualquer outro lugar que suporte MCP
🚀 Sempre atualizado — novas ferramentas e correções são enviadas automaticamente

👉 Comece gratuitamente em useproxy.dev →

Prefere executar você mesmo? A configuração completa de auto-hospedagem está documentada abaixo.

Hospedado vs. Auto-hospedado

	Hospedado — Proxy (useproxy.dev)	Auto-hospedado
Tempo de configuração	Nenhum — conecte e use	Ambiente Python + configuração
Chaves de API necessárias	Nenhuma	ScrapeCreators + Gemini
Infraestrutura	Totalmente gerenciada	Você executa e mantém
Atualizações	Automáticas	Manuais `git pull`
Funciona em ChatGPT, Claude, Cursor, Manus	✅	✅
Melhor para	A maioria dos usuários que só querem os dados	Desenvolvedores que querem personalizar o código

Para a maioria das pessoas, a versão hospedada é o caminho mais rápido. Escolha auto-hospedagem se você quiser especificamente modificar ou estender o servidor por conta própria.

Exemplos de Prompts

Análise de Marca Única

How many ads is 'AnthropicAI' running? What's their split across video and image?

What messaging is 'AnthropicAI' running right now in their ads?

Analyze the video ads from 'Nike' and extract their visual storytelling strategy, pacing, and brand messaging techniques.

Análise em Lote (Novo!)

Compare the current advertising strategies across Nike, Adidas, and Under Armour. Show me their ad volumes, messaging themes, and creative approaches.

Do a deep comparison to the messaging between 'AnthropicAI', 'Perplexity AI' and 'OpenAI'. Give it a nice forwardable summary.

Analyze the holiday campaign strategies for Coca-Cola, Pepsi, Dr Pepper, and Sprite. What themes are they using?

Get the current ads for all major streaming services: Netflix, Disney+, Hulu, HBO Max, Amazon Prime Video, and Apple TV+. Compare their positioning strategies.

Instalação

Pré-requisitos

Python 3.12+
Aplicativo Anthropic Claude Desktop (ou Cursor)
Pip (gerenciador de pacotes Python), instale com python -m pip install
Uma chave de API para um provedor de dados de anúncios, definida como SCRAPECREATORS_API_KEY (veja a configuração abaixo)
Uma chave de API Google Gemini para análise de vídeo (opcional, necessária apenas para anúncios em vídeo)

Prefere não lidar com chaves de API? Veja a Versão Hospedada acima para pular a configuração completamente.

Clone e execute o script de instalação

git clone https://github.com/proxy-intell/facebook-ads-library-mcp.git
cd facebook-ads-library-mcp

# For macOS/Linux:
./install.sh

# For Windows:
install.bat

O script de instalação irá:

Criar um ambiente virtual para isolamento de dependências
Instalar todas as dependências necessárias
Configurar seus arquivos de configuração

Configure suas chaves de API Edite o arquivo .env que foi criado e adicione suas chaves de API:

Defina sua chave de API de dados de anúncios como SCRAPECREATORS_API_KEY
Obtenha sua chave de API Gemini em Google AI Studio (opcional, para análise de vídeo)

Siga a configuração MCP exibida O script de instalação mostrará a configuração exata para adicionar ao Claude Desktop ou Cursor.

Instalação Manual

Se você preferir instalar manualmente:

Clone este repositório

git clone https://github.com/proxy-intell/facebook-ads-library-mcp.git
cd facebook-ads-library-mcp

Crie um ambiente virtual e instale as dependências

python3 -m venv venv
./venv/bin/pip install -r requirements.txt

Configure as chaves de API Copie o modelo e configure suas chaves de API: Para obter chaves de API:

Defina sua chave de API de dados de anúncios como SCRAPECREATORS_API_KEY no arquivo .env
Obtenha uma chave de API Google Gemini aqui (opcional, para análise de vídeo)

Conecte ao servidor MCP Adicione a configuração do servidor MCP à configuração do seu Claude Desktop ou Cursor: Substitua {{PATH_TO_PROJECT}} pelo caminho completo de onde você clonou este repositório. Observação: A configuração usa o interpretador Python do ambiente virtual (venv/bin/python) para melhor isolamento de dependências e confiabilidade. Observação: As chaves de API agora são carregadas automaticamente do arquivo .env, então você não precisa passá-las como argumentos de linha de comando. Para Claude Desktop: Salve isso como claude_desktop_config.json no diretório de configuração do seu Claude Desktop em: Para Cursor: Salve isso como mcp.json no diretório de configuração do seu Cursor em:
Reinicie o Claude Desktop / Cursor Abra o Claude Desktop e você deve ver a Biblioteca de Anúncios do Facebook como uma integração disponível. Ou reinicie o Cursor.

Detalhes Técnicos

O Claude envia solicitações ao servidor MCP Python
O servidor MCP agrupa e otimiza inteligentemente as consultas à API de dados de anúncios
O cache inteligente reduz chamadas de API redundantes e melhora o desempenho
O monitoramento de créditos evita interrupções no fluxo de trabalho com tratamento proativo de erros
Os dados fluem de volta pela cadeia até o Claude com informações aprimoradas de lote

Ferramentas MCP Disponíveis (Aprimoradas)

Este servidor MCP fornece ferramentas para interagir com objetos da biblioteca de anúncios do Facebook:

Nome da Ferramenta	Descrição	Suporte a Lote
`get_meta_platform_id`	Retorna o ID da plataforma dado um ou vários nomes de marcas	✅ Várias marcas
`get_meta_ads`	Recupera anúncios para página(s) específica(s) (ID da plataforma)	✅ Vários IDs de plataforma
`analyze_ad_image`	Analisa imagens de anúncios para elementos visuais, texto, cores e composição	⚡ Cache aprimorado
`analyze_ad_video`	Analisa um único vídeo de anúncio usando IA Gemini para insights abrangentes	⚡ Cache aprimorado
`analyze_ad_videos_batch`	NOVO - Analisa vários vídeos em uma única chamada de API para eficiência de tokens	🎬 ~88% de economia de tokens
`get_cache_stats`	Obtém estatísticas sobre mídia em cache (imagens e vídeos) e uso de armazenamento	-
`search_cached_media`	Pesquisa mídia previamente analisada por marca, cores, pessoas ou tipo de mídia	-
`cleanup_media_cache`	Limpa arquivos de mídia antigos em cache para liberar espaço em disco	-

Solução de Problemas

Problemas Comuns

🆕 Créditos de API Esgotados:

Quando você vir uma mensagem de "créditos de API esgotados", você precisa recarregar sua conta
A mensagem de erro inclui um link direto para o painel do seu provedor
Você pode verificar seu saldo de créditos atual e comprar mais créditos lá
O servidor retomará automaticamente o funcionamento quando os créditos estiverem disponíveis

🆕 Limite de Taxa Excedido:

Se você atingir os limites de taxa, o servidor informará quanto tempo esperar
Operações em lote ajudam a reduzir a chance de atingir os limites de taxa
Considere espaçar solicitações em lote grandes se você atingir os limites com frequência

Erro de Chave de API Não Encontrada:

Certifique-se de que seu arquivo .env esteja no diretório raiz do projeto
Se você não tiver um arquivo .env, copie-o do modelo: cp .env.template .env
Verifique se suas chaves de API estão formatadas corretamente sem aspas
Verifique se o arquivo .env contém SCRAPECREATORS_API_KEY=your_key_here
Para análise de vídeo, certifique-se de que GEMINI_API_KEY=your_key_here também seja adicionado

Análise de Vídeo Não Funciona:

Confirme que você tem uma chave de API Google Gemini válida no seu arquivo .env
A análise de vídeo requer a variável de ambiente GEMINI_API_KEY

Problemas de Conexão com o Servidor MCP:

Verifique se o caminho na sua configuração MCP aponta para o local correto
Certifique-se de ter criado um ambiente virtual e instalado as dependências com python3 -m venv venv && ./venv/bin/pip install -r requirements.txt
Certifique-se de que sua configuração MCP use o caminho Python do ambiente virtual (terminando com /venv/bin/python)
Reinicie o Claude Desktop/Cursor após alterações de configuração

Para solução de problemas adicional de integração com Claude Desktop, veja a documentação MCP. A documentação inclui dicas úteis para verificar logs e resolver problemas comuns.

FAQ

Qual é a maneira mais fácil de usar o MCP da Biblioteca de Anúncios do Facebook? A maneira mais fácil é a versão hospedada da Proxy (useproxy.dev). Ela não requer chaves de API, instalação ou servidor — você a conecta ao ChatGPT, Claude, Cursor ou qualquer cliente MCP e começa a consultar imediatamente. Você pode começar gratuitamente.

Preciso de uma chave de API para usar este MCP? Somente se você auto-hospedar. A versão hospedada em useproxy.dev lida com todo o acesso a dados por você, então nenhuma chave ScrapeCreators ou Gemini é necessária. A auto-hospedagem requer um SCRAPECREATORS_API_KEY (e uma chave Gemini para análise de vídeo).

Com quais clientes MCP ele funciona? Tanto a versão hospedada quanto a auto-hospedada funcionam com ChatGPT, Claude (Desktop e web), Cursor, Manus e qualquer outro cliente que suporte o Model Context Protocol.

Existe uma versão gratuita? Sim — a versão hospedada da Proxy oferece um plano gratuito para que você possa começar a analisar anúncios sem qualquer configuração.

Devo auto-hospedar ou usar a versão hospedada? Use a versão hospedada se você quiser apenas acesso rápido e confiável aos dados da Biblioteca de Anúncios do Facebook com zero manutenção — isso atende à maioria dos usuários. Auto-hospede apenas se quiser modificar ou estender o código do servidor por conta própria.

Feedback

Seu feedback será imensamente apreciado. Por favor, conte-nos quais recursos dessa lista você gostaria de ver a seguir ou solicite recursos totalmente novos.

Licença

Este projeto é licenciado sob a Licença MIT.

Feito com ❤️ pela equipe da Proxy.