Código abierto

Un servidor MCP para Google Ads que puedes alojar tú mismo

42 herramientas para que ChatGPT o Claude manejen tus cuentas de Google Ads —leer el rendimiento, investigar palabras clave, armar campañas, cambiar presupuestos— detrás de límites que el modelo no puede negociar.

¿Es tu primera vez con esto? Nuestra explicación cubre qué es un servidor MCP para Google Ads, qué puede exponer y qué revisar antes de confiar en uno. Leer la explicación del servidor MCP

• 42 herramientas
• Licencia MIT
• Java 21 · Spring Boot

Por qué esto es más difícil de lo que parece

Los tokens de desarrollador empiezan restringidos

Un token de desarrollador nuevo de Google Ads tiene acceso de Test Account y solo alcanza cuentas de prueba. Tu primera ejecución correcta devuelve listas vacías y parece un error. El acceso Basic requiere una solicitud y la aprobación tarda días, así que empieza por ahí.

Las cuentas administrador no tienen campañas

Google devuelve sobre todo cuentas administrador (MCC), que no pueden publicar anuncios. Las que sí pueden son sus cuentas hijas, y a cada una hay que dirigirse indicando el administrador desde el cual se encontró.

La API habla en micros

Los importes llegan en millonésimas. Un presupuesto de 5000000 son cinco unidades de moneda, y equivocarse por un millón no es un redondeo: es un incidente de gasto.

Los importes no traen moneda

Nada en la respuesta dice en qué moneda está un número. Si informas un presupuesto de una cuenta en UAH con signo de dólar, quien lo lea verá una cifra unas cuarenta veces mayor que la real.

GAQL no es SQL

No hay joins, y la segmentación cambia lo que significa una fila, no solo cuántas hay. Si pides la segmentación equivocada, tus totales se multiplican sin avisar.

Las versiones se retiran, no se marcan como obsoletas

Google apaga las versiones antiguas de la API en fechas publicadas. Una versión fija deja de funcionar un día determinado, así que tiene que ser configurable sin esperar una nueva release.

Lo que no va a hacer

Vale la pena leerlo antes del comando de instalación, porque un error acá gasta dinero real.

• Nada se publica solo. La herramienta que crea campañas no tiene un campo de estado en su esquema, así que el modelo no puede crear una campaña activa ni intentándolo.
• Solo se pueden activar las campañas que creó este servidor. Una hecha en la interfaz de Google Ads se rechaza, porque su presupuesto nunca pasó por el control del límite.
• Cada cambio de presupuesto se compara con un límite que tú defines, en la moneda de la propia cuenta publicitaria. El servidor rechaza el cambio; nunca lo reduce en silencio para que quepa.
• Cada herramienta de escritura tiene un límite diario, así que un modelo atascado en un bucle no puede hacer cientos de cambios en una cuenta.
• Un control aparte rechaza una ráfaga de llamadas en poco tiempo, sea cual sea la herramienta.
• Por defecto autentica a un solo operador: una contraseña y una cuenta, no un inicio de sesión multiusuario que tengas que proteger.

Cómo encaja todo

mcp-core

La capa de protocolo y un pequeño servidor de autorización OAuth 2.1: registro dinámico de clientes, PKCE, rotación de refresh tokens con detección de reutilización y una pantalla de consentimiento. No sabe nada de publicidad, así que sirve para cualquier herramienta que quieras que un asistente ejecute.

cliente de google-ads

Un cliente de la API de Google Ads sin Spring y sin MCP. Se puede usar por separado desde cualquier código que necesite hablar con Google Ads, y por eso se publica como su propio artefacto.

servidor de google-ads

El servidor ejecutable: las 42 herramientas, los límites de gasto, el registro de auditoría de cada escritura y el flujo que conecta una cuenta de Google Ads.

Las 42 herramientas

Las de lectura necesitan permiso de lectura; las de escritura necesitan permiso de escritura y pasan por los límites de arriba.

• Cuentas, facturación y ritmo de gasto — Listar las cuentas accesibles, revisar la configuración de facturación y ver el gasto de hoy frente al presupuesto de cada campaña.
• Campañas — Listar, crear en pausa, activar, pausar, reanudar y cambiar presupuestos, ofertas, configuración, segmentación, negativas y objetivos de conversión.
• Grupos de anuncios y anuncios — Crear y editar grupos de anuncios, listar anuncios con su veredicto de políticas, y crear o actualizar anuncios de búsqueda responsivos.
• Palabras clave y términos de búsqueda — Listar, agregar, quitar y editar palabras clave, leer las consultas que la gente escribió de verdad y obtener ideas de palabras clave.
• Performance Max — Leer y editar grupos de recursos, sus recursos y su contenido multimedia, los temas de búsqueda y los recursos de marca a nivel de campaña.
• Vínculos a sitios — Listar, crear, actualizar y quitar vínculos a sitios a nivel de campaña.
• Informes — Rendimiento por cuenta, campaña, grupo de anuncios o palabra clave, más geografía, audiencias y acciones de conversión.

Ejecutarlo tú mismo

La imagen publicada no necesita Java ni compilación. Copia el archivo de entorno de ejemplo, complétalo y arráncalo: cada valor está documentado en el mismo lugar donde lo defines.

# 1. the compose file and the documented environment template
curl -O https://raw.githubusercontent.com/loomascale/ads-mcp/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/loomascale/ads-mcp/main/.env.example

# 2. fill it in — every value says what it is and how to generate it
cp .env.example .env

# 3. start it; the image is prebuilt, so there is no JDK and no Maven here
docker compose up

curl -s -X POST https://your-host/mcp \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools[].name'

Un requisito es lento más que difícil: el token de desarrollador de Google Ads necesita una solicitud a Google y la aprobación tarda días. Empieza por eso antes que por nada más.

Preguntas