Servidor MCP Google Ads API v20

Un servidor complet de Model Context Protocol (MCP) que proporciona accés complet a la funcionalitat de Google Ads API v20. Aquest servidor permet als assistents d'IA realitzar qualsevol operació de Google Ads mitjançant comandes en llenguatge natural.

Funcionalitats

Cobertura completa de l'API

• Gestió de comptes: Llistar comptes, obtenir informació del compte, veure la jerarquia
• Gestió de campanyes: Crear, actualitzar, pausar/reanudar campanyes amb totes les funcions v20
• Gestió de grups d'anuncis: Operacions CRUD completes per a grups d'anuncis
• Creació d'anuncis: Anuncis de cerca responsives, anuncis de text ampliats i més
• Gestió d'actius: Carregar i gestionar imatges, actius de text
• Gestió de pressupostos: Crear i gestionar pressupostos compartits
• Gestió de paraules clau: Afegir paraules clau, paraules clau negatives (incloent negatives a nivell de campanya Performance Max)
• Informes i analítica: Consultes GAQL personalitzades, informes de rendiment, termes de cerca
• Funcionalitats avançades: Recomanacions, historial de canvis, experiments

Funcionalitats intel·ligents

• Lògica de reintents automàtica: Gestiona errors transients amb retard exponencial
• Documentació d'errors: Enllaços a la documentació oficial d'errors de Google Ads API
• Gestió de fracassos parcials: Continua el processament quan algunes operacions fallen
• Actualització automàtica de tokens: Refresca automàticament els tokens OAuth
• Auto-reescritura: Pot consultar la documentació i reintentar operacions fallides

Instal·lació

# Instal·la amb pip
pip install -e .

# O instal·la les dependències directament
pip install mcp google-ads pydantic httpx tenacity python-dotenv beautifulsoup4 structlog

Configuració

Variables d'entorn

Crea un fitxer .env o estableix aquestes variables d'entorn:

# Autenticació OAuth2
GOOGLE_ADS_CLIENT_ID=your_client_id
GOOGLE_ADS_CLIENT_SECRET=your_client_secret
GOOGLE_ADS_REFRESH_TOKEN=your_refresh_token

# O Autenticació amb compte de servei
GOOGLE_ADS_SERVICE_ACCOUNT_PATH=/path/to/service-account.json
GOOGLE_ADS_IMPERSONATED_EMAIL=user@example.com  # Opcional

# Requerit per a tots els mètodes d'autenticació
GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token
GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890  # ID del compte gestor si s'aplica

Fitxer de configuració

Alternativament, crea un fitxer de configuració a ~/.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"
}

Configuració MCP

Afegeix a la configuració de 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"
      }
    }
  }
}

Exemples d'ús

Operacions bàsiques

# Llista tots els comptes
Use the list_accounts tool

# Crea una campanya
Use create_campaign with customer_id="1234567890", name="Summer Sale 2025", 
budget_amount=100.0, campaign_type="SEARCH"

# Obtén el rendiment de la campanya
Use get_campaign_performance with customer_id="1234567890", date_range="LAST_30_DAYS"

Consultes avançades

# Executa una consulta GAQL personalitzada
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

Funcionalitats Performance Max (v20)

# Afegir paraules clau negatives a una campanya Performance Max
Use add_negative_keywords with customer_id="1234567890", 
campaign_id="123", keywords=["cheap", "discount", "free"]

Gestió d'errors

El servidor proporciona informació detallada dels errors:

• Tipus i codi d'error
• Missatge llegible per a humans
• Si l'error és reintérpretable
• Enllaç a la documentació oficial
• Suggestions per a corregir errors comuns

Desenvolupament

Executar proves

pytest tests/

Afegeix nous eines

1. Afegeix la definició de l'eina a _register_tools() en tools.py
2. Implementa el mètode de gestió
3. Actualitza la documentació

Depuració

# Executa amb registre de depuració
export LOG_LEVEL=DEBUG
python -m google-ads-mcp

Notes de seguretat

• No commiteu mai credencials al control de versions
• Utilitzeu comptes de servei per a entorns de producció
• Activa la 2FA als comptes de Google Ads
• Rotació regular dels tokens de refresc
• Monitoritza l'ús de l'API i estableix alertes

Suport de versió d'API

Aquest servidor està construït per a Google Ads API v20 (llançada a juny de 2025) i inclou:

• Paraules clau negatives a nivell de campanya per a Performance Max
• Informes Demand Gen millorats amb segmentació per canals
• Conversions comparables de plataforma
• Totes les funcionalitats i millores específiques de v20

Llicència

MIT License - Veure fitxer LICENSE per a det