Servidor MCP de Google Ads API v20

Un completo servidor de Protocolo de contexto de modelo (MCP) que proporciona acceso completo 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 de 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 decampañ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 responsive, anuncios de texto expandido y más
• Gestión de activos: Cargue y gestione imágenes y activos de texto
• Gestión depresupuestos: Cree y gestione presupuestos compartidos
• Gestión depalabras clave: Añadir palabras clave, palabras clave negativas (incluidas las 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

Funciones inteligentes

• Lógica de reintentos automáticos: Maneja errores transitorios con retroceso exponencial
• Documentación de errores: Enlaces a la documentación oficial de errores de Google Ads API
• Gestión de errores parciales: Continúa el procesamiento cuando fallan algunas operaciones
• Actualización automática de tokens: Actualiza automáticamente los tokens OAuth
• Autorreescritura: Puede buscar documentación y reintentar operaciones fallidas

Instalación

# Instalar con pip pip install -e . # O instalar las dependencias directamente pip install mcp google-ads pydantic httpx tenacity python-dotenv beautifulsoup4 structlog

Configuración

Variables de entorno

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

# Autenticación OAuth2 GOOGLE_ADS_CLIENT_ID=your_client_id GOOGLE_ADS_CLIENT_SECRET=your_client_secret GOOGLE_ADS_REFRESH_TOKEN=your_refresh_token # O autenticación de cuenta de servicio GOOGLE_ADS_SERVICE_ACCOUNT_PATH=/path/to/service-account.json GOOGLE_ADS_IMPERSONATED_EMAIL=user@example.com # Opcional # Obligatorio para todos los métodos de autenticación GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890 # ID de cuenta de administrador si procede

Archivo de configuración

Como alternativa, 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 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": "tu_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

# Listar todas las cuentas Utilizar la herramienta list_accounts Crear una campaña Utilizar create_campaign con customer_id="1234567890", name="Rebajas de verano 2025", budget_amount=100.0, campaign_type="SEARCH" Obtener el rendimiento de la campaña Utilizar get_campaign_performance con customer_id="1234567890", date_range="LAST_30_DAYS"

Consultas avanzadas

# Use run_gaql_query con la consulta: 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)

# Añada palabras clave negativas a la campaña de Performance Max Use add_negative_keywords with customer_id="1234567890", campaign_id="123", keywords=["barato", "descuento", "gratis"]

Tratamiento de errores

El servidor proporciona información detallada sobre los errores:

• Tipo y código de error
• Mensaje legible
• Si el error es reintentable
• Enlace a la documentación oficial
• Sugerencias para solucionar errores comunes

Desarrollo

Ejecución de pruebas

pytest pruebas/

Añadir nuevas herramientas

1. Añadir definición de herramienta a _register_tools() en tools.py
2. Implementar el método handler
3. Actualizar documentación

Depuración

# Ejecutar con registro de depuración export LOG_LEVEL=DEBUG python -m google-ads-mcp

Notas de seguridad

• No confirmar nunca las credenciales en el control de versiones
• Utilice cuentas de servicio para entornos de producción
• Habilite 2FA en las cuentas de Google Ads
• Rote periódicamente los tokens de actualización
• Supervise el uso de la API y establezca alertas

Compatibilidad con la versión de API

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

• Palabras clave negativas a nivel de campaña para Performance Max
• Informes de generación de demanda mejorados con segmentación de canales
• Conversiones comparables con la plataforma
• Todas las funciones y mejoras específicas de la versión 20

Licencia

Licencia MIT - Consulte el archivo LICENSE para más detalles

Contribución

Las contribuciones son bienvenidas Por favor:

1. Fork el repositorio
2. Crear una rama de características
3. Añadir pruebas para nuevas funcionalidades
4. Envía un pull request

Soporte

Para cuestiones y preguntas:

• Consulta la documentación de Google Ads API
• Revise los mensajes de error y los enlaces a la documentación
• Abrir una incidencia en GitHub