Google Ads API v20

Fornece acesso completo à API do Google Ads v20. Requer credenciais OAuth2 ou de Conta de Serviço para configuração.

GitHub
11
Experimente este MCPPatrocinado

Documentação

Servidor MCP Google Ads API v20

Um servidor abrangente do Model Context Protocol (MCP) que fornece acesso completo à funcionalidade da Google Ads API v20. Este servidor permite que assistentes de IA executem qualquer operação do Google Ads por meio de comandos em linguagem natural.

Recursos

Cobertura Completa da API

  • Gerenciamento de Contas: Listar contas, obter informações da conta, visualizar hierarquia
  • Gerenciamento de Campanhas: Criar, atualizar, pausar/retomar campanhas com todos os recursos da v20
  • Gerenciamento de Grupos de Anúncios: Operações completas de CRUD para grupos de anúncios
  • Criação de Anúncios: Anúncios de pesquisa responsivos, anúncios de texto expandidos e muito mais
  • Gerenciamento de Ativos: Enviar e gerenciar imagens, ativos de texto
  • Gerenciamento de Orçamentos: Criar e gerenciar orçamentos compartilhados
  • Gerenciamento de Palavras-chave: Adicionar palavras-chave, palavras-chave negativas (incluindo negativas em nível de campanha do Performance Max)
  • Relatórios e Análises: Consultas GAQL personalizadas, relatórios de desempenho, termos de pesquisa
  • Recursos Avançados: Recomendações, histórico de alterações, experimentos

Recursos Inteligentes

  • Lógica Automática de Repetição: Lida com erros transitórios usando backoff exponencial
  • Documentação de Erros: Links para a documentação oficial de erros da Google Ads API
  • Tratamento de Falhas Parciais: Continua o processamento quando algumas operações falham
  • Atualização Automática de Token: Atualiza automaticamente os tokens OAuth
  • Auto-Reescrita: Pode consultar a documentação e repetir operações com falha

Instalação

# Install with pip
pip install -e .

# Or install dependencies directly
pip install mcp google-ads pydantic httpx tenacity python-dotenv beautifulsoup4 structlog

Configuração

Variáveis de Ambiente

Crie um arquivo .env ou defina estas variáveis de ambiente:

# OAuth2 Authentication
GOOGLE_ADS_CLIENT_ID=your_client_id
GOOGLE_ADS_CLIENT_SECRET=your_client_secret
GOOGLE_ADS_REFRESH_TOKEN=your_refresh_token

# OR Service Account Authentication
GOOGLE_ADS_SERVICE_ACCOUNT_PATH=/path/to/service-account.json
GOOGLE_ADS_IMPERSONATED_EMAIL=user@example.com  # Optional

# Required for all auth methods
GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token
GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890  # Manager account ID if applicable

Arquivo de Configuração

Alternativamente, crie um arquivo de configuração em ~/.config/google-ads-mcp/config.json:

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "refresh_token": "your_refresh_token",
  "developer_token": "your_developer_token",
  "login_customer_id": "1234567890"
}

Configuração do MCP

Adicione à configuração do seu Claude Desktop (~/.config/claude/mcp.json):

{
  "mcpServers": {
    "google-ads": {
      "command": "python",
      "args": ["-m", "google-ads-mcp"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your_token",
        "GOOGLE_ADS_CLIENT_ID": "your_client_id",
        "GOOGLE_ADS_CLIENT_SECRET": "your_secret",
        "GOOGLE_ADS_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Exemplos de Uso

Operações Básicas

# List all accounts
Use the list_accounts tool

# Create a campaign
Use create_campaign with customer_id="1234567890", name="Summer Sale 2025", 
budget_amount=100.0, campaign_type="SEARCH"

# Get campaign performance
Use get_campaign_performance with customer_id="1234567890", date_range="LAST_30_DAYS"

Consultas Avançadas

# Run custom GAQL query
Use run_gaql_query with query:
SELECT campaign.name, metrics.clicks, metrics.conversions
FROM campaign
WHERE metrics.impressions > 1000
  AND segments.date DURING LAST_7_DAYS
ORDER BY metrics.clicks DESC

Recursos do Performance Max (v20)

# Add negative keywords to Performance Max campaign
Use add_negative_keywords with customer_id="1234567890", 
campaign_id="123", keywords=["cheap", "discount", "free"]

Tratamento de Erros

O servidor fornece informações detalhadas sobre erros:

  • Tipo e código do erro
  • Mensagem legível para humanos
  • Indicação se o erro pode ser repetido
  • Link para a documentação oficial
  • Sugestões para corrigir erros comuns

Desenvolvimento

Executando Testes

pytest tests/

Adicionando Novas Ferramentas

  1. Adicione a definição da ferramenta a _register_tools() em tools.py
  2. Implemente o método do manipulador
  3. Atualize a documentação

Depuração

# Run with debug logging
export LOG_LEVEL=DEBUG
python -m google-ads-mcp

Notas de Segurança

  • Nunca envie credenciais para o controle de versão
  • Use contas de serviço para ambientes de produção
  • Ative a autenticação de dois fatores (2FA) nas contas do Google Ads
  • Rotacione os tokens de atualização regularmente
  • Monitore o uso da API e configure alertas

Suporte à Versão da API

Este servidor foi desenvolvido para a Google Ads API v20 (lançada em junho de 2025) e inclui:

  • Palavras-chave negativas em nível de campanha para Performance Max
  • Relatórios aprimorados do Demand Gen com segmentação por canal
  • Conversões comparáveis entre plataformas
  • Todos os recursos e melhorias específicos da v20

Licença

Licença MIT - Consulte o arquivo LICENSE para obter detalhes

Contribuição

Contribuições são bem-vindas! Por favor:

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Adicione testes para a nova funcionalidade
  4. Envie um pull request

Suporte

Para problemas e perguntas: