Google Ads

Servidor MCP do Google Ads 🚀

Um servidor Model Context Protocol com tecnologia FastMCP para integração com a API do Google Ads e autenticação automática OAuth 2.0

Conecte a API do Google Ads diretamente ao Claude Desktop e a outros clientes MCP com autenticação OAuth 2.0 perfeita, atualização automática de tokens, consultas GAQL e recursos de pesquisa de palavras-chave.

Seu navegador não suporta a tag de vídeo.

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 ajuda e atualizações

👉 Comunidade Slack - AI in Ads

Experimente também o servidor MCP do Facebook Ads

👉 Facebook Ads MCP - Facebook Ads MCP

✨ Recursos

• 🔐 OAuth 2.0 Automático - Autenticação única no navegador com atualização automática
• 🔄 Gerenciamento Inteligente de Tokens - Lida com tokens expirados automaticamente
• 📊 Execução de Consultas GAQL - Execute qualquer consulta da Google Ads Query Language
• 🏢 Gerenciamento de Contas - Liste e gerencie contas do Google Ads
• 🔍 Pesquisa de Palavras-Chave - Gere ideias de palavras-chave com dados de volume de pesquisa
• 🚀 Framework FastMCP - Construído no padrão MCP moderno
• 🖥️ Pronto para Claude Desktop - Integração direta com o Claude Desktop
• 🛡️ Armazenamento Local Seguro - Tokens armazenados localmente, nunca expostos

📋 Ferramentas Disponíveis

Ferramenta	Descrição	Parâmetros	Exemplo de Uso
list_accounts	Listar todas as contas do Google Ads acessíveis	Nenhum	"Liste todas as minhas contas do Google Ads"
run_gaql	Executar consultas GAQL com formatação personalizada	customer_id, query, manager_id (opcional)	"Mostre-me o desempenho da campanha para a conta 1234567890"
run_keyword_planner	Gerar ideias de palavras-chave com métricas	customer_id, keywords, manager_id, page_url, opções de intervalo de datas	"Gere ideias de palavras-chave para 'marketing digital'"

Nota: Todas as ferramentas lidam automaticamente com a autenticação - nenhum parâmetro de token é necessário!

🚀 Início Rápido

Pré-requisitos

Antes de configurar o servidor MCP, você precisará de:

• Python 3.10+ instalado
• Uma conta no Google Cloud Platform
• Uma conta do Google Ads com acesso à API

🔧 Etapa 1: Configuração do Google Cloud Platform

1.1 Criar Projeto no Google Cloud

1. Acesse o Google Cloud Console
2. Crie um novo projeto:
   • Clique em "Selecionar um projeto" → "Novo projeto"
   • Digite o nome do projeto (ex.: "Google Ads MCP")
   • Clique em "Criar"

1.2 Ativar a API do Google Ads

1. No seu Google Cloud Console:
   • Vá para "APIs e Serviços" → "Biblioteca"
   • Pesquise por "Google Ads API"
   • Clique nela e pressione "Ativar"

1.3 Criar Credenciais OAuth 2.0

1. Vá para "APIs e Serviços" → "Credenciais"
2. Clique em "+ CRIAR CREDENCIAIS" → "ID do Cliente OAuth 2.0"
3. Configure a tela de consentimento (se for a primeira vez):
   • Clique em "Configurar Tela de Consentimento"
   • Escolha "Externo" (a menos que você tenha o Google Workspace)
   • Preencha os campos obrigatórios:
     • Nome do aplicativo: "Google Ads MCP"
     • E-mail de suporte ao usuário: Seu e-mail
     • Contato do desenvolvedor: Seu e-mail
   • Clique em "Salvar e Continuar" em todas as etapas
4. Crie o Cliente OAuth:
   • Tipo de aplicativo: "Aplicativo de desktop"
   • Nome: "Google Ads MCP Client"
   • Clique em "Criar"
5. Baixe as credenciais:
   • Clique no botão "Baixar JSON"
   • Salve o arquivo como client_secret_[long-string].json no diretório do seu projeto

🔧 Etapa 2: Configuração da API do Google Ads

2.1 Obter Token de Desenvolvedor

1. Entre no Google Ads
2. Vá para Ferramentas e Configurações (ícone de chave inglesa na navegação superior)
3. Em "Configuração", clique em "Centro de API"
4. Aceite os Termos de Serviço se solicitado
5. Clique em "Solicitar token"
6. Preencha o formulário de inscrição:
   • Descreva seu caso de uso (ex.: "Integração MCP para análise de campanhas")
   • Forneça detalhes técnicos sobre sua implementação
7. Envie e aguarde a aprovação (geralmente 1-3 dias úteis)

Nota: Inicialmente, você receberá um token de teste com funcionalidade limitada. Após os testes, você pode solicitar acesso de produção.

2.2 Encontre Seu Token de Desenvolvedor

Após a aprovação:

1. Volte ao Centro de API no Google Ads
2. Copie seu Token de Desenvolvedor (formato: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX)

🔧 Etapa 3: Instalação e Configuração

3.1 Clonar e Instalar

# Clone the repository
git clone https://github.com/yourusername/google-ads-mcp-server.git
cd google-ads-mcp-server

# Create virtual environment (recommended)
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

3.2 Configuração de Ambiente

Crie um arquivo .env no diretório do seu projeto:

# Copy the example file
cp .env.example .env

Edite .env com suas credenciais:

# Required: Google Ads API Developer Token
GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here

# Required: Path to OAuth credentials JSON file (downloaded from Google Cloud)
GOOGLE_ADS_OAUTH_CONFIG_PATH=/full/path/to/your/client_secret_file.json

Exemplo de arquivo .env:

GOOGLE_ADS_DEVELOPER_TOKEN=ABCDEFG1234567890
GOOGLE_ADS_OAUTH_CONFIG_PATH=/Users/john/google-ads-mcp/client_secret_138737274875-abc123.apps.googleusercontent.com.json

🖥️ Etapa 4: Integração com Claude Desktop

4.1 Localizar Configuração do Claude

Encontre o arquivo de configuração do Claude Desktop:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

4.2 Adicionar Configuração do Servidor MCP

Edite o arquivo de configuração e adicione seu servidor MCP do Google Ads:

{
  "mcpServers": {
    "google-ads": {
      "command": "/full/path/to/your/project/.venv/bin/python",
      "args": [
        "/full/path/to/your/project/server.py"
      ]
    }
  }
}

Exemplo Real:

{
  "mcpServers": {
    "google-ads": {
      "command": "/Users/marble-dev-01/workspace/google_ads_with_fastmcp/.venv/bin/python",
      "args": [
        "/Users/marble-dev-01/workspace/google_ads_with_fastmcp/server.py"
      ]
    }
  }
}

Importante:

• Use caminhos absolutos para todos os locais de arquivo
• No Windows, use barras normais / ou barras duplas invertidas \\ nos caminhos
• Substitua your_developer_token_here pelo seu token de desenvolvedor real

4.3 Reiniciar o Claude Desktop

Feche e reinicie o Claude Desktop para carregar a nova configuração.

🔐 Etapa 5: Autenticação pela Primeira Vez

5.1 Iniciar Fluxo OAuth

1. Abra o Claude Desktop
2. Tente qualquer comando do Google Ads, por exemplo:

   "List all my Google Ads accounts"
   

5.2 Concluir Autenticação

1. O navegador abre automaticamente na página OAuth do Google
2. Entre com sua conta do Google (aquela com acesso ao Google Ads)
3. Conceda permissões clicando em "Permitir"
4. O navegador mostra a página de sucesso
5. Volte ao Claude - seu comando será concluído automaticamente!

5.3 Verificar Configuração

Após a autenticação, você deve ver:

• Um arquivo google_ads_token.json criado no diretório do seu projeto
• Suas contas do Google Ads listadas na resposta do Claude

📖 Exemplos de Uso

Operações Básicas de Conta

"List all my Google Ads accounts"

"Show me the account details and which ones have active campaigns"

Análise de Campanhas

"Show me campaign performance for account 1234567890 in the last 30 days"

"Get conversion data for all campaigns in the last week"

"Which campaigns have the highest cost per conversion?"

Pesquisa de Palavras-Chave

"Generate keyword ideas for 'digital marketing' using account 1234567890"

"Find keyword opportunities for 'AI automation' with search volume data"

"Research keywords for the page https://example.com/services"

Consultas GAQL Personalizadas

"Run this GAQL query for account 1234567890:
SELECT campaign.name, metrics.clicks, metrics.cost_micros 
FROM campaign 
WHERE segments.date DURING LAST_7_DAYS"

"Get keyword performance data:
SELECT ad_group_criterion.keyword.text, metrics.ctr, metrics.average_cpc
FROM keyword_view 
WHERE metrics.impressions > 100"

🔍 Exemplos Avançados de GAQL

Desempenho de Campanhas com Receita

SELECT 
  campaign.id,
  campaign.name, 
  metrics.clicks, 
  metrics.impressions,
  metrics.cost_micros,
  metrics.conversions,
  metrics.conversions_value
FROM campaign 
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.cost_micros DESC

Análise de Desempenho de Palavras-Chave

SELECT 
  campaign.name,
  ad_group_criterion.keyword.text, 
  ad_group_criterion.keyword.match_type,
  metrics.ctr,
  metrics.average_cpc,
  metrics.quality_score
FROM keyword_view 
WHERE segments.date DURING LAST_7_DAYS
  AND metrics.impressions > 100
ORDER BY metrics.conversions DESC

Detalhamento de Desempenho por Dispositivo

SELECT 
  campaign.name,
  segments.device,
  metrics.clicks,
  metrics.cost_micros,
  metrics.conversions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
  AND campaign.status = 'ENABLED'

📁 Estrutura do Projeto

google-ads-mcp-server/
├── server.py                           # Main MCP server
├── oauth/
│   ├── __init__.py                     # Package initialization
│   └── google_auth.py                  # OAuth authentication logic
├── google_ads_token.json               # Auto-generated token storage (gitignored)
├── client_secret_[long-string].json    # Your OAuth credentials (gitignored)
├── .env                                # Environment variables (gitignored)
├── .env.example                        # Environment template
├── .gitignore                          # Git ignore file
├── requirements.txt                    # Python dependencies
├── LICENSE                             # MIT License
└── README.md                           # This file

🔒 Segurança e Boas Práticas

Segurança de Arquivos

• ✅ Arquivos de credenciais estão no gitignore - Nunca enviados para controle de versão
• ✅ Armazenamento local de tokens - Tokens armazenados em google_ads_token.json localmente
• ✅ Variáveis de ambiente - Dados sensíveis no arquivo .env
• ✅ Atualização automática - Tempo mínimo de exposição do token

Permissões de Arquivo Recomendadas

# Set secure permissions for sensitive files
chmod 600 .env
chmod 600 google_ads_token.json
chmod 600 client_secret_*.json

Considerações de Produção

1. Use variáveis de ambiente em vez de arquivos .env em produção
2. Implemente limite de taxa para respeitar as cotas da API
3. Monitore o uso da API no Google Cloud Console
4. Armazenamento seguro de tokens com controles de acesso adequados
5. Rotação regular de tokens para maior segurança

🛠️ Solução de Problemas

Problemas de Autenticação

Problema	Sintomas	Solução
Nenhum token encontrado	Mensagem "Iniciando fluxo OAuth"	✅ Normal na primeira configuração - conclua a autenticação no navegador
Falha na atualização do token	Erro "Falha ao atualizar token"	✅ Exclua google_ads_token.json e reautentique
Falha no fluxo OAuth	Erro no navegador ou sem resposta	Verifique o caminho do arquivo de credenciais e a conexão com a internet
Permissão negada	"Acesso negado" no navegador	Garanta que a conta do Google tenha acesso ao Google Ads

Problemas de Configuração

Problema	Sintomas	Solução
Variáveis de ambiente ausentes	"Variável de ambiente não definida"	Verifique o arquivo .env e a seção env da configuração do Claude
Arquivo não encontrado	"FileNotFoundError"	Verifique os caminhos absolutos na configuração
Erros de importação de módulo	"ModuleNotFoundError"	Execute pip install -r requirements.txt
Problemas com o caminho do Python	"Comando não encontrado"	Use o caminho absoluto para o executável do Python

Problemas com Claude Desktop

Problema	Sintomas	Solução
Servidor não está conectando	Nenhuma ferramenta do Google Ads disponível	Reinicie o Claude Desktop, verifique a sintaxe do arquivo de configuração
Configuração JSON inválida	Erros de inicialização do Claude	Valide a sintaxe JSON no arquivo de configuração
Erros de permissão	"Permissão negada" na inicialização	Verifique as permissões e os caminhos dos arquivos

Problemas de API

Problema	Sintomas	Solução
ID de cliente inválido	"Cliente não encontrado"	Use o formato de 10 dígitos sem hífens: 1234567890
Cota da API excedida	Erro "Cota excedida"	Aguarde a redefinição da cota ou solicite um aumento
Token de desenvolvedor inválido	"Falha na autenticação"	Verifique o token no Centro de API do Google Ads
Erros de sintaxe GAQL	"Consulta inválida"	Verifique a sintaxe GAQL e os nomes dos campos

Modo de Depuração

Ative o registro detalhado para solução de problemas:

# Add to server.py for debugging
import logging
logging.basicConfig(level=logging.DEBUG)

Obtendo Ajuda

Se você encontrar problemas:

1. Verifique a mensagem de erro com atenção - ela geralmente indica o problema exato
2. Verifique se todos os caminhos de arquivo são absolutos e corretos
3. Garanta que as variáveis de ambiente estejam configuradas corretamente
4. Verifique o Google Cloud Console para cotas de API e cobrança
5. Reinicie o Claude Desktop após qualquer alteração de configuração

🚀 Configuração Avançada

Modo de Transporte HTTP

Para implantação web ou acesso remoto:

# Start server in HTTP mode
python3 server.py --http

Configuração do Claude Desktop para HTTP:

{
  "mcpServers": {
    "google-ads": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Armazenamento Personalizado de Tokens

Modifique o local de armazenamento de tokens em oauth/google_auth.py:

# Custom token file location
def get_token_path():
    return "/custom/secure/path/google_ads_token.json"

Configuração de Conta de Gerente

Para gerenciar várias contas sob um MCC:

# Add to .env file
GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890

🤝 Contribuindo

Aceitamos contribuições! Veja como começar:

Configuração de Desenvolvimento

# Fork and clone the repository
git clone https://github.com/yourusername/google-ads-mcp-server.git
cd google-ads-mcp-server

# Create development environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Set up development environment
cp .env.example .env
# Add your development credentials to .env

Fazendo Alterações

1. Crie um branch de recurso: git checkout -b feature/amazing-feature
2. Faça suas alterações com testes apropriados
3. Teste minuciosamente com diferentes configurações de conta
4. Atualize a documentação conforme necessário
5. Faça commit das alterações: git commit -m 'Add amazing feature'
6. Envie para o branch: git push origin feature/amazing-feature
7. Abra um Pull Request com descrição detalhada

Testando Suas Alterações

# Test authentication flow
python3 server.py --test-auth

# Test API connectivity
python3 -c "
from oauth.google_auth import get_oauth_credentials
creds = get_oauth_credentials()
print('✅ Authentication successful!')
"

# Test with Claude Desktop
# Add your server to Claude config and test various commands

📊 Limites e Cotas da API

Cotas da API do Google Ads

• Acesso básico: 15.000 operações por dia
• Acesso padrão: 40.000 operações por dia
• Taxa de solicitações: 1.600 solicitações por minuto por token de desenvolvedor

Boas Práticas para Uso da API

1. Armazene resultados em cache quando possível para reduzir chamadas de API
2. Use intervalos de datas para limitar o volume de dados
3. Agrupe solicitações quando houver suporte
4. Monitore o uso no Google Cloud Console
5. Implemente lógica de repetição para erros de limite de taxa

Gerenciamento de Cotas

# Monitor usage in Google Cloud Console
# Go to APIs & Services → Quotas
# Search for "Google Ads API" to see current usage

📄 Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

---

Licença MIT

Copyright (c) 2025 Google Ads MCP Server Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

📈 Roteiro

Recursos Futuros

• 🔄 Pesquisa aprimorada de palavras-chave com análise de concorrentes
• 📊 Visualização de dados integrada com gráficos e tabelas
• 🤖 Sugestões de otimização com IA
• 📝 Ferramentas de criação e gerenciamento de campanhas
• 🔍 Recursos avançados de relatórios
• 🌐 Suporte a vários idiomas

---

Feito com ❤️ para a comunidade MCP

Conecte seus dados do Google Ads diretamente a assistentes de IA e desbloqueie insights poderosos de publicidade por meio de conversas em linguagem natural.