Google Ads

Servidor MCP de Google Ads 🚀

Un servidor de Model Context Protocol impulsado por FastMCP para la integración con la API de Google Ads con autenticación automática OAuth 2.0

Conecta la API de Google Ads directamente a Claude Desktop y otros clientes MCP con autenticación OAuth 2.0 sin interrupciones, renovación automática de tokens, consultas GAQL y capacidades de investigación de palabras clave.

Tu navegador no admite la etiqueta de video.

Configuración sencilla con un clic

Para una experiencia de configuración más simple, ofrecemos instaladores listos para usar:

👉 Descargar instalador - https://gomarble.ai/mcp

Únete a nuestra comunidad para obtener ayuda y actualizaciones

👉 Comunidad de Slack - AI in Ads

Prueba también el servidor MCP de Facebook Ads

👉 Facebook Ads MCP - Facebook Ads MCP

✨ Características

• 🔐 OAuth 2.0 automático - Autenticación en el navegador de una sola vez con renovación automática
• 🔄 Gestión inteligente de tokens - Maneja tokens caducados automáticamente
• 📊 Ejecución de consultas GAQL - Ejecuta cualquier consulta del Lenguaje de Consultas de Google Ads
• 🏢 Gestión de cuentas - Lista y gestiona cuentas de Google Ads
• 🔍 Investigación de palabras clave - Genera ideas de palabras clave con datos de volumen de búsqueda
• 🚀 Marco FastMCP - Construido sobre el estándar MCP moderno
• 🖥️ Listo para Claude Desktop - Integración directa con Claude Desktop
• 🛡️ Almacenamiento local seguro - Los tokens se almacenan localmente, nunca se exponen

📋 Herramientas disponibles

Herramienta	Descripción	Parámetros	Ejemplo de uso
list_accounts	Lista todas las cuentas de Google Ads accesibles	Ninguno	"Lista todas mis cuentas de Google Ads"
run_gaql	Ejecuta consultas GAQL con formato personalizado	customer_id, query, manager_id (opcional)	"Muéstrame el rendimiento de la campaña para la cuenta 1234567890"
run_keyword_planner	Genera ideas de palabras clave con métricas	customer_id, keywords, manager_id, page_url, opciones de rango de fechas	"Genera ideas de palabras clave para 'marketing digital'"

Nota: Todas las herramientas manejan la autenticación automáticamente: ¡no se requieren parámetros de token!

🚀 Inicio rápido

Requisitos previos

Antes de configurar el servidor MCP, necesitarás:

• Python 3.10+ instalado
• Una cuenta de Google Cloud Platform
• Una cuenta de Google Ads con acceso a la API

🔧 Paso 1: Configuración de Google Cloud Platform

1.1 Crear un proyecto de Google Cloud

1. Ve a Consola de Google Cloud
2. Crea un nuevo proyecto:
   • Haz clic en "Seleccionar un proyecto" → "Nuevo proyecto"
   • Ingresa el nombre del proyecto (por ejemplo, "Google Ads MCP")
   • Haz clic en "Crear"

1.2 Habilitar la API de Google Ads

1. En tu Consola de Google Cloud:
   • Ve a "APIs y servicios" → "Biblioteca"
   • Busca "Google Ads API"
   • Haz clic en ella y presiona "Habilitar"

1.3 Crear credenciales OAuth 2.0

1. Ve a "APIs y servicios" → "Credenciales"
2. Haz clic en "+ CREAR CREDENCIALES" → "ID de cliente OAuth 2.0"
3. Configura la pantalla de consentimiento (si es la primera vez):
   • Haz clic en "Configurar pantalla de consentimiento"
   • Elige "Externo" (a menos que tengas Google Workspace)
   • Completa los campos obligatorios:
     • Nombre de la aplicación: "Google Ads MCP"
     • Correo de soporte al usuario: Tu correo
     • Contacto de desarrollador: Tu correo
   • Haz clic en "Guardar y continuar" a través de todos los pasos
4. Crea el cliente OAuth:
   • Tipo de aplicación: "Aplicación de escritorio"
   • Nombre: "Cliente de Google Ads MCP"
   • Haz clic en "Crear"
5. Descarga las credenciales:
   • Haz clic en el botón "Descargar JSON"
   • Guarda el archivo como client_secret_[long-string].json en tu directorio de proyecto

🔧 Paso 2: Configuración de la API de Google Ads

2.1 Obtener el token de desarrollador

1. Inicia sesión en Google Ads
2. Ve a Herramientas y configuración (icono de llave inglesa en la navegación superior)
3. En "Configuración", haz clic en "Centro de API"
4. Acepta los Términos de servicio si se te solicita
5. Haz clic en "Solicitar token"
6. Completa el formulario de solicitud:
   • Describe tu caso de uso (por ejemplo, "Integración MCP para análisis de campañas")
   • Proporciona detalles técnicos sobre tu implementación
7. Envía y espera la aprobación (generalmente de 1 a 3 días hábiles)

Nota: Inicialmente obtendrás un token de prueba con funcionalidad limitada. Después de las pruebas, puedes solicitar acceso de producción.

2.2 Encuentra tu token de desarrollador

Una vez aprobado:

1. Vuelve al Centro de API en Google Ads
2. Copia tu token de desarrollador (formato: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX)

🔧 Paso 3: Instalación y configuración

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 Configuración del entorno

Crea un archivo .env en tu directorio de proyecto:

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

Edita .env con tus credenciales:

# 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

Ejemplo de archivo .env:

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

🖥️ Paso 4: Integración con Claude Desktop

4.1 Localizar la configuración de Claude

Encuentra tu archivo de configuración de Claude Desktop:

macOS:

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

Windows:

%APPDATA%\Claude\claude_desktop_config.json

4.2 Agregar la configuración del servidor MCP

Edita el archivo de configuración y agrega tu servidor MCP de Google Ads:

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

Ejemplo 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:

• Usa rutas absolutas para todas las ubicaciones de archivos
• En Windows, usa barras diagonales / o dobles barras invertidas \\ en las rutas
• Reemplaza your_developer_token_here con tu token de desarrollador real

4.3 Reiniciar Claude Desktop

Cierra y reinicia Claude Desktop para cargar la nueva configuración.

🔐 Paso 5: Autenticación por primera vez

5.1 Iniciar el flujo OAuth

1. Abre Claude Desktop
2. Prueba cualquier comando de Google Ads, por ejemplo:

   "List all my Google Ads accounts"
   

5.2 Completar la autenticación

1. El navegador se abre automáticamente en la página de OAuth de Google
2. Inicia sesión con tu cuenta de Google (la que tiene acceso a Google Ads)
3. Otorga permisos haciendo clic en "Permitir"
4. El navegador muestra una página de éxito
5. Vuelve a Claude - ¡tu comando se completará automáticamente!

5.3 Verificar la configuración

Después de la autenticación, deberías ver:

• Un archivo google_ads_token.json creado en tu directorio de proyecto
• Tus cuentas de Google Ads listadas en la respuesta de Claude

📖 Ejemplos de uso

Operaciones básicas de cuenta

"List all my Google Ads accounts"

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

Análisis de campañas

"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?"

Investigación de palabras clave

"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"

🔍 Ejemplos avanzados de GAQL

Rendimiento de campañas con ingresos

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álisis de rendimiento de palabras clave

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

Desglose de rendimiento 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'

📁 Estructura del proyecto

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

🔒 Seguridad y mejores prácticas

Seguridad de archivos

• ✅ Los archivos de credenciales están en gitignore - Nunca se envían al control de versiones
• ✅ Almacenamiento local de tokens - Los tokens se almacenan en google_ads_token.json localmente
• ✅ Variables de entorno - Datos sensibles en el archivo .env
• ✅ Renovación automática - Tiempo mínimo de exposición del token

Permisos de archivos recomendados

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

Consideraciones de producción

1. Usa variables de entorno en lugar de archivos .env en producción
2. Implementa limitación de velocidad para respetar las cuotas de la API
3. Monitorea el uso de la API en la Consola de Google Cloud
4. Asegura el almacenamiento de tokens con controles de acceso adecuados
5. Rotación regular de tokens para mayor seguridad

🛠️ Solución de problemas

Problemas de autenticación

Problema	Síntomas	Solución
No se encuentran tokens	Mensaje "Iniciando flujo OAuth"	✅ Normal para la primera configuración: completa la autenticación en el navegador
Error al renovar el token	Error "Error al renovar el token"	✅ Elimina google_ads_token.json y vuelve a autenticarte
Error en el flujo OAuth	Error en el navegador o sin respuesta	Verifica la ruta del archivo de credenciales y la conexión a internet
Permiso denegado	"Acceso denegado" en el navegador	Asegúrate de que la cuenta de Google tenga acceso a Google Ads

Problemas de configuración

Problema	Síntomas	Solución
Faltan variables de entorno	"Variable de entorno no configurada"	Verifica el archivo .env y la sección env de la configuración de Claude
Archivo no encontrado	"FileNotFoundError"	Verifica las rutas absolutas en la configuración
Errores de importación de módulos	"ModuleNotFoundError"	Ejecuta pip install -r requirements.txt
Problemas con la ruta de Python	"Comando no encontrado"	Usa la ruta absoluta al ejecutable de Python

Problemas con Claude Desktop

Problema	Síntomas	Solución
El servidor no se conecta	No hay herramientas de Google Ads disponibles	Reinicia Claude Desktop, verifica la sintaxis del archivo de configuración
Configuración JSON inválida	Errores al iniciar Claude	Valida la sintaxis JSON en el archivo de configuración
Errores de permisos	"Permiso denegado" al iniciar	Verifica los permisos de archivos y rutas

Problemas de API

Problema	Síntomas	Solución
ID de cliente inválido	"Cliente no encontrado"	Usa el formato de 10 dígitos sin guiones: 1234567890
Cuota de API excedida	Error "Cuota excedida"	Espera a que se restablezca la cuota o solicita un aumento
Token de desarrollador inválido	"Error de autenticación"	Verifica el token en el Centro de API de Google Ads
Errores de sintaxis GAQL	"Consulta inválida"	Verifica la sintaxis de GAQL y los nombres de campos

Modo de depuración

Habilita el registro detallado para solucionar problemas:

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

Obtener ayuda

Si encuentras problemas:

1. Revisa el mensaje de error cuidadosamente - generalmente indica el problema exacto
2. Verifica que todas las rutas de archivos sean absolutas y correctas
3. Asegúrate de que las variables de entorno estén configuradas correctamente
4. Revisa la Consola de Google Cloud para cuotas de API y facturación
5. Reinicia Claude Desktop después de cualquier cambio de configuración

🚀 Configuración avanzada

Modo de transporte HTTP

Para implementación web o acceso remoto:

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

Configuración de Claude Desktop para HTTP:

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

Almacenamiento personalizado de tokens

Modifica la ubicación de almacenamiento de tokens en oauth/google_auth.py:

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

Configuración de cuenta de administrador

Para gestionar múltiples cuentas bajo un MCC:

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

🤝 Contribuciones

¡Damos la bienvenida a las contribuciones! Así es como puedes comenzar:

Configuración de desarrollo

# 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

Hacer cambios

1. Crea una rama de características: git checkout -b feature/amazing-feature
2. Haz tus cambios con pruebas apropiadas
3. Prueba a fondo con diferentes configuraciones de cuenta
4. Actualiza la documentación según sea necesario
5. Confirma los cambios: git commit -m 'Add amazing feature'
6. Empuja a la rama: git push origin feature/amazing-feature
7. Abre una Solicitud de extracción con una descripción detallada

Probar tus cambios

# 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

📊 Límites y cuotas de la API

Cuotas de la API de Google Ads

• Acceso básico: 15,000 operaciones por día
• Acceso estándar: 40,000 operaciones por día
• Tasa de solicitudes: 1,600 solicitudes por minuto por token de desarrollador

Mejores prácticas para el uso de la API

1. Almacena en caché los resultados cuando sea posible para reducir las llamadas a la API
2. Usa rangos de fechas para limitar el volumen de datos
3. Procesa solicitudes por lotes cuando sea compatible
4. Monitorea el uso en la Consola de Google Cloud
5. Implementa lógica de reintento para errores de límite de velocidad

Gestión de cuotas

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

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulta el archivo LICENCIA para más detalles.

---

Licencia 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.

📈 Hoja de ruta

Próximas características

• 🔄 Investigación de palabras clave mejorada con análisis de competidores
• 📊 Visualización de datos integrada con gráficos y diagramas
• 🤖 Sugerencias de optimización impulsadas por IA
• 📝 Herramientas de creación y gestión de campañas
• 🔍 Capacidades de informes avanzados
• 🌐 Soporte multilingüe

---

Hecho con ❤️ para la comunidad MCP

Conecta tus datos de Google Ads directamente a asistentes de IA y desbloquea información publicitaria poderosa a través de conversaciones en lenguaje natural.