Servidor MCP de Google Ads 🚀

Un servidor de protocolo de contexto de modelo impulsado por FastMCP para la integración de Google Ads API con autenticación automática OAuth 2.0

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

Su navegador no admite la etiqueta de vídeo.

Fácil configuración con un solo clic

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

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

Únete a nuestra comunidad para obtener ayuda y actualizaciones

👉 Comunidad Slack -AI en anuncios

Prueba también el servidor mcp de Facebook ads

👉 Facebook Ads MCP -Facebook Ads MCP

✨ Características

• 🔐 O Auth 2.0 automático: autenticación única en el navegador con actualización automática
• 🔄 Gestión inteligente de tokens: gestiona los tokens caducados de forma automática
• 📊 Ejecución de consultas GAQL - Ejecuta cualquier consulta de Google Ads Query Language
• 🏢 Administración de cuentas: enumera y administra las cuentas de Google Ads
• 🔍 Investigación de palabras clave: genere ideas de palabras clave con datos de volumen de búsqueda
• 🚀 FastMCP Framework - Construido sobre el moderno estándar MCP
• 🖥️ Claude Desktop Ready - Integración directa con Claude Desktop
• 🛡️ Secure Local Storage - Tokens almacenados localmente, nunca expuestos

herramientas disponibles

Nota: Todas las herramientas gestionan automáticamente la autenticación, ¡no se necesitan 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. Vaya a la consola de Google Cloud
2. Cree un nuevo proyecto
   • Haz clic en "Seleccionar un proyecto" → "Nuevo proyecto"
   • Introduzca el nombre del proyecto (por ejemplo, "Google Ads MCP")
   • Haga clic en "Crear"

1.2 Habilitar Google Ads API

1. En tu consola de Google Cloud
   • Ve a "API y servicios" → "Biblioteca"
   • Busca "Google Ads API"
   • Haz clic en ella y pulsa "Habilitar"

1.3 Crear credenciales de OAuth 2.0

1. Vaya a "API y servicios" → "Credenciales"
2. Haz clic en "+ CREAR CREDENCIALES" → "ID de cliente de OAuth 2.0"
3. Configurarpantalla de consentimiento (si es la primera vez)
   • Haga clic en "Configurar pantalla de consentimiento"
   • Seleccione "Externo" (a menos que tenga Google Workspace)
   • Rellene los campos obligatorios
     • Nombre de la aplicación: "Google Ads MCP"
     • Correo electrónico de asistencia al usuario: Su correo electrónico
     • Contacto del desarrollador: Tu email
   • Haga clic en "Guardar y continuar" en todos los pasos
4. Crear cliente OAuth
   • Tipo de aplicación: "Aplicación de escritorio"
   • Nombre: "Cliente MCP de Google Ads"
   • Haga clic en "Crear"
5. Descargar credenciales
   • Haga clic en el botón "Descargar JSON
   • Guarde el archivo como client_secret_[long-string].json en el directorio de su proyecto

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

2.1 Obtener token de desarrollador

1. Inicie 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", haga clic en "Centro de API"
4. Acepte las Condiciones del servicio si se le solicita
5. Haga clic en "Solicitar token"
6. Rellene el formulario de solicitud
   • Describa su caso de uso (por ejemplo, "Integración de MCP para el análisis de campañas")
   • Proporcione detalles técnicos sobre su implementación
7. Envíe la solicitud y espere la aprobación (normalmente entre 1 y 3 días laborables)

Nota: Inicialmente obtendrá un token de prueba con funcionalidad limitada. Después de la prueba, puede solicitar el acceso de producción.

2.2 Obtenga su código de desarrollador

Una vez aprobado:

1. Vuelva al Centro de API de Google Ads
2. Copie su código de desarrollador (formato: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX)

🔧 Paso 3: Instalación y configuración

3.1 Clonar e instalar

# Clonar el repositorio git clone https://github.com/yourusername/google-ads-mcp-server.git cd google-ads-mcp-server # Crear entorno virtual (recomendado) python3 -m venv .venv source .venv/bin/activate # En Windows: .venv\Scripts\activate # Instalar dependencias pip install -r requirements.txt

3.2 Configuración del entorno

Cree un archivo .env en el directorio de su proyecto:

# Copia el archivo de ejemplo cp .env.ejemplo .env

Edite .env con sus credenciales:

# Requerido: Google Ads API Developer Token GOOGLE_ADS_DEVELOPER_TOKEN=su_token_developer_here # Requerido: Ruta al archivo JSON de credenciales OAuth (descargado de 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 Localice la configuración de Claude

Localice su 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 Añadir la configuración del servidor MCP

Edite el archivo de configuración y añada su 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:

• Utilice rutas absolutas para todas las ubicaciones de archivos
• En Windows, utilice barras inclinadas / o barras invertidas dobles \\ en las rutas
• Sustituya your_developer_token_here por su código de desarrollador real

4.3 Reinicie Claude Desktop

Cierre y reinicie Claude Desktop para cargar la nueva configuración.

🔐 Paso 5: Autenticación por primera vez

5.1 Activar el flujo de OAuth

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

   "Listar todas mis cuentas de Google Ads"

5.2 Completar la autenticación

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

5.3 Verificar la configuración

Después de la autenticación, usted debe ver:

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

📖 Ejemplos de uso

Operaciones básicas con cuentas

"Listar todas mis cuentas de Google Ads" "Mostrarme los detalles de la cuenta y cuáles tienen campañas activas"

Análisis de campañas

"Muéstrame el rendimiento de las campañas de la cuenta 1234567890 en los últimos 30 días" "Obtén los datos de conversión de todas las campañas de la última semana" "¿Qué campañas tienen el mayor coste por conversión?"

Búsqueda de palabras clave

"Generar ideas de palabras clave para 'marketing digital' usando la cuenta 1234567890" "Encontrar oportunidades de palabras clave para 'automatización de IA' con datos de volumen de búsqueda" "Investigar palabras clave para la página https://example.com/services"

Consultas GAQL personalizadas

"Ejecuta esta consulta GAQL para la cuenta 1234567890: SELECT campaign.name, metrics.clicks, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_7_DAYS" "Obtén datos de rendimiento de palabras clave: 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ña 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 del 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 del 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 # Servidor MCP principal ├── oauth/ │ ├── __init__.py # Inicialización del paquete │ └── google_auth.py # Lógica de autenticación OAuth ├── google_ads_token.json # Almacenamiento del token generado automáticamente (gitignored) ├── client_secret_[long-string].json # Tus credenciales OAuth (gitignored) ├── .env # Variables de entorno (gitignored) ├── .env.example # Plantilla de entorno ├── .gitignore # Archivo Git ignore ├── requirements.txt # Dependencias de Python ├── LICENSE # Licencia MIT └── README.md # Este archivo

🔒 Seguridad y buenas prácticas

Seguridad de los archivos

• ✅ Los archivos de credenciales son gitignored - Nunca se comprometen al control de versiones
• ✅ Almacenamiento local de tokens - Los tokens se almacenan en google_ads_token.json de forma local
• ✅ Variables de entorno - Datos sensibles en el archivo .env
• ✅ Actualización automática - Tiempo mínimo de exposición del token

Permisos de archivos recomendados

# Establecer permisos seguros para archivos sensibles chmod 600 .env chmod 600 google_ads_token.json chmod 600 client_secret_*.json

Consideraciones de producción

1. Utilice variables de entorno en lugar de archivos .env en producción
2. Implemente la limitación de velocidad para respetar las cuotas de la API
3. Supervisar el uso de la API en Google Cloud Console
4. Almacenamiento seguro de tokens con controles de acceso adecuados
5. Rotación periódica de tokens para mejorar la seguridad

🛠️ Solución de problemas

Problemas de autenticación

Problemas de configuración

Problemas con Claude Desktop

Problemas de API

Modo de depuración

Habilite el registro detallado para la solución de problemas:

# Añadir a server.py para depuración import logging logging.basicConfig(level=logging.DEBUG)

Obtener ayuda

Si se encuentra con problemas:

1. Compruebe cuidadosamente el mensaje de error - normalmente indica el problema exacto
2. Compruebe que todas las rutas de los archivos son absolutas y correctas
3. Asegúrate de quelas variables de entorno estén configuradas correctamente
4. Comprueba enGoogle Cloud Console las cuotas de API y la facturación
5. Reinicia Claude Desktop después de cualquier cambio de configuración

configuración avanzada

Modo de transporte HTTP

Para despliegue web o acceso remoto:

# Iniciar el servidor en modo HTTP python3 server.py --http

Claude Desktop config para HTTP:

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

Almacenamiento personalizado de tokens

Modificar ubicación de almacenamiento de token en oauth/google_auth.py:

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

Configuración de cuentas de administrador

Para gestionar múltiples cuentas bajo un MCC:

# Añadir al archivo .env GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890

🤝 Contribuir

Las contribuciones son bienvenidas A continuación te explicamos cómo empezar:

Configuración de desarrollo

# Fork y clonar el repositorio git clone https://github.com/yourusername/google-ads-mcp-server.git cd google-ads-mcp-server # Crear entorno de desarrollo python3 -m venv .venv source .venv/bin/activate # Instalar dependencias pip install -r requirements.txt # Configurar entorno de desarrollo cp .env.example .env # Añadir tus credenciales de desarrollo a .env

Realización de cambios

1. Crear una rama:git checkout -b feature/amazing-feature
2. Haga sus cambios con las pruebas apropiadas
3. Pruebea fondo con diferentes configuraciones de cuenta
4. Actualice la documentación según sea necesario
5. Confirmar los cambios:git commit -m 'Add amazing feature'
6. Empujar a la rama:git push origin feature/amazing-feature
7. Abrir una Pull Request con una descripción detallada

Probar los cambios

# Prueba el flujo de autenticación python3 server.py --test-auth # Prueba la conectividad de la API python3 -c " from oauth.google_auth import get_oauth_credentials creds = get_oauth_credentials() print('✅ ¡Autenticación correcta!') " # Prueba con Claude Desktop # Añade tu servidor a Claude config y prueba varios comandos

📊 Límites y cuotas de la API

Cuotas de la API de anuncios de Google

• Acceso básico: 15.000 operaciones al día
• Acceso estándar: 40.000 operaciones al día
• Tasa de solicitudes: 1.600 solicitudes por minuto por token de desarrollador

Prácticas recomendadas para el uso de la API

1. Almacene en caché los resultados siempre que sea posible para reducir las llamadas a la API
2. Utilice intervalos de fechas para limitar el volumen de datos
3. Realizar solicitudes por lotes cuando sea posible
4. Supervisar el uso en Google Cloud Console
5. Implementar una lógica de reintento para los errores de límite de velocidad

Gestión de cuotas

# Supervisar el uso en Google Cloud Console Ir a API y servicios → Cuotas Buscar "Google Ads API" para ver el uso actual

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - ver el archivo LICENSE para más detalles.

Licencia MIT

Copyright (c) 2025 Google Ads MCP Server Contributors Por la presente se concede permiso, de forma gratuita, a cualquier persona que obtenga una copia de este software y de los archivos de documentación asociados (el "Software"), para comerciar con el Software sin restricciones, incluidos, entre otros, los derechos a utilizar, copiar, modificar, fusionar, publicar, distribuir, sublicenciar y/o vender copias del Software, y a permitir que las personas a las que se proporcione el Software lo hagan, con sujeción a las siguientes condiciones: El aviso de copyright anterior y este aviso de permiso se incluirán en todas las copias o partes sustanciales del Software.

EL SOFTWARE SE SUMINISTRA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUIDAS, ENTRE OTRAS, LAS GARANTÍAS DE COMERCIABILIDAD, IDONEIDAD PARA UN FIN DETERMINADO Y NO INFRACCIÓN. EN NINGÚN CASO LOS AUTORES O LOS TITULARES DE LOS DERECHOS DE AUTOR SERÁN RESPONSABLES DE NINGUNA RECLAMACIÓN, DAÑO U OTRA RESPONSABILIDAD, YA SEA EN UNA ACCIÓN CONTRACTUAL, EXTRACONTRACTUAL O DE OTRO TIPO, QUE SURJA DE, O ESTÉ RELACIONADA CON EL SOFTWARE O EL USO U OTRAS OPERACIONES CON EL SOFTWARE

📈 Hoja de ruta

Próximas funciones

• 🔄 Investigación de palabras clave mejorada con análisis de la competencia
• 📊 Visualización de datos integrada con tablas y gráficos
• 🤖 S ugerencias de optimización basadas en IA
• 📝 Herramientas de creación y gestión de campañas
• 🔍 F unciones avanzadas de generación de informes
• compatible con varios idiomas

Hecho con ❤️ para la comunidad MCP

Conecta tus datos de Google Ads directamente a los asistentes de IA y desbloquea poderosos conocimientos publicitarios a través de conversaciones en lenguaje natural.