Google Ads API v20

Google Ads API v20 MCP Server

Un servidor completo del Model Context Protocol (MCP) que proporciona acceso total a la funcionalidad de Google Ads API v20. Este servidor permite a los asistentes de IA realizar cualquier operación de Google Ads mediante comandos en lenguaje natural.

Características

Cobertura completa de la API

• Gestión de cuentas: Listar cuentas, obtener información de la cuenta, ver jerarquía
• Gestión de campañas: Crear, actualizar, pausar/reanudar campañas con todas las funciones de v20
• Gestión de grupos de anuncios: Operaciones CRUD completas para grupos de anuncios
• Creación de anuncios: Anuncios de búsqueda responsivos, anuncios de texto expandido y más
• Gestión de activos: Subir y gestionar imágenes y activos de texto
• Gestión de presupuestos: Crear y gestionar presupuestos compartidos
• Gestión de palabras clave: Añadir palabras clave y palabras clave negativas (incluyendo negativas a nivel de campaña de Performance Max)
• Informes y análisis: Consultas GAQL personalizadas, informes de rendimiento, términos de búsqueda
• Funciones avanzadas: Recomendaciones, historial de cambios, experimentos

Características inteligentes

• Lógica de reintento automático: Maneja errores transitorios con retroceso exponencial
• Documentación de errores: Enlaces a la documentación oficial de errores de Google Ads API
• Manejo de fallos parciales: Continúa procesando cuando fallan algunas operaciones
• Actualización automática de tokens: Actualiza automáticamente los tokens OAuth
• Auto-corrección: Puede consultar documentación y reintentar operaciones fallidas

Instalación

# Install with pip
pip install -e .

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

Configuración

Variables de entorno

Cree un archivo .env o establezca estas variables de entorno:

# 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

Archivo de configuración

Alternativamente, cree un archivo de configuración en ~/.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ón de MCP

Añada a su configuración 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"
      }
    }
  }
}

Ejemplos de uso

Operaciones 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 avanzadas

# 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

Características de 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"]

Manejo de errores

El servidor proporciona información detallada sobre errores:

• Tipo y código de error
• Mensaje legible para humanos
• Si el error se puede reintentar
• Enlace a la documentación oficial
• Sugerencias para corregir errores comunes

Desarrollo

Ejecutar pruebas

pytest tests/

Añadir nuevas herramientas

1. Añada la definición de la herramienta a _register_tools() en tools.py
2. Implemente el método del controlador
3. Actualice la documentación

Depuración

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

Notas de seguridad

• Nunca envíe credenciales al control de versiones
• Utilice cuentas de servicio para entornos de producción
• Active la verificación en dos pasos (2FA) en las cuentas de Google Ads
• Rote los tokens de actualización con regularidad
• Supervise el uso de la API y configure alertas

Soporte de versiones de API

Este servidor está diseñado para Google Ads API v20 (lanzada en junio de 2025) e incluye:

• Palabras clave negativas a nivel de campaña para Performance Max
• Informes mejorados de Demand Gen con segmentación por canal
• Conversiones comparables entre plataformas
• Todas las funciones y mejoras específicas de v20

Licencia

Licencia MIT: consulte el archivo LICENSE para obtener más detalles

Contribuciones

¡Las contribuciones son bienvenidas! Por favor:

1. Haga un fork del repositorio
2. Cree una rama de funcionalidad
3. Añada pruebas para la nueva funcionalidad
4. Envíe un pull request

Soporte

Para problemas y preguntas:

• Consulte la documentación de Google Ads API
• Revise los mensajes de error y los enlaces de documentación
• Abra un issue en GitHub