🌐 Elegí tu idioma / Choose your language
Google Ads MCP
Administrá Google Ads desde Claude — no sólo lo mires.
Servidor MCP read/write para Google Ads API v25, self-hosted, con confirmación humana, auditoría, aislamiento MCC y acciones pendientes durables.
Creado y mantenido por Alejandro José · Akela
Qué problema resuelve · Cómo funciona · Tutorial paso a paso · Ejemplos · Seguridad · Capacidades · Sobre Akela
Qué es
Google Ads MCP es un servidor Model Context Protocol que conecta Claude —o cualquier cliente MCP compatible— con la Google Ads API v25 para trabajar sobre cuentas reales.
No está pensado como un dashboard más. Está pensado para hacer el trabajo cotidiano de una agencia o un equipo de performance desde una conversación:
- leer reportes y GAQL;
- encontrar desperdicio de presupuesto;
- crear y modificar campañas;
- administrar keywords, anuncios, assets y audiencias;
- trabajar con Conversiones, Customer Match, Performance Max y Experiments;
- operar varias cuentas desde una MCC;
- ejecutar cambios con human-in-the-loop en vez de darle a la IA permiso ciego sobre el gasto.
Todo corre en tu infraestructura. Tus credenciales de Google Ads no necesitan pasar por un SaaS intermediario.
Por qué existe
Leer datos desde una IA es útil. Operar una cuenta es otra cosa.
El trabajo real de performance incluye decisiones como:
“Mostrame los términos de búsqueda de los últimos 7 días, detectá los que gastaron y no convirtieron, proponé negativas y no publiques nada hasta que yo lo confirme.”
O:
“Revisá la campaña de Search, encontrá qué grupo perdió volumen por presupuesto, compará CPA y proponeme el cambio más razonable.”
O:
“Creá la estructura de una campaña nueva, dejala PAUSED y mostrámela antes de tocar delivery.”
Google Ads MCP cierra esa distancia entre analizar y hacer, sin eliminar el control humano.
Diseñado para agencias y operadores
Cómo funciona
flowchart LR
U[Vos] --> C[Claude / Cliente MCP]
C --> M[Google Ads MCP\nlocal / self-hosted]
M --> R{¿Lectura o escritura?}
R -->|Lectura| G[Google Ads API v25]
R -->|Escritura| S[Safety Layer]
S --> P[Preview + pending_action_id]
P --> H{Confirmás?}
H -->|No| X[Cancelada\nno cambia la cuenta]
H -->|Sí| G
G --> A[(SQLite Audit Log)]
Una escritura normal
proponer → previsualizar → confirmar → ejecutar → auditar
La IA puede preparar el cambio. Vos decidís cuándo se ejecuta.
Ejemplos reales de uso
1. Search Terms → negativas
Vos:
Revisá los términos de búsqueda de los últimos 7 días.
Todo lo que gastó más de USD 20 y tuvo 0 conversiones,
proponelo como negativa. No confirmes nada.
Claude:
→ get_search_terms_report(...)
→ add_negative_keywords(...)
Propuesta:
- free
- jobs
- diy
- template
pending_action_id: 7f3a2c1e
Nada cambió todavía.
Vos:
Confirmá 7f3a2c1e.
Claude:
→ confirm_pending_action("7f3a2c1e")
✓ Cambio aplicado y registrado en audit.db
2. Auditoría de una cuenta
Analizá esta cuenta durante los últimos 30 días.
Separame campañas por CPA, ROAS, gasto y pérdida de impression share.
No hagas cambios. Dame primero 5 prioridades.
3. Crear sin publicar
Prepará una campaña Search para este servicio.
Creá presupuesto, campaña, grupo, keywords y RSA,
pero dejá todo PAUSED y pedime confirmación antes de cada escritura.
4. MCC
Listá las cuentas permitidas de mi MCC y mostrámelas ordenadas por gasto de los últimos 7 días.
Más ejemplos listos para usar: docs/EXAMPLES.md.
Tutorial paso a paso
Paso 0 — Requisitos
Necesitás:
- Python 3.11+;
- acceso a una cuenta Google Ads;
- Developer Token de Google Ads;
- OAuth 2.0 Client ID / Client Secret;
- Refresh Token con scope de Google Ads;
- opcionalmente un Login Customer ID si trabajás con MCC.
La guía detallada de credenciales está en docs/SETUP.md.
Paso 1 — Clonar e instalar
git clone https://github.com/akelaonline/MCP-Google-Ads.git
cd MCP-Google-Ads
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e ".[dev]"
En Windows PowerShell:
.venv\Scripts\Activate.ps1
Paso 2 — Crear tu .env
cp .env.example .env
Completá como mínimo:
GOOGLE_ADS_DEVELOPER_TOKEN=
GOOGLE_ADS_CLIENT_ID=
GOOGLE_ADS_CLIENT_SECRET=
GOOGLE_ADS_REFRESH_TOKEN=
GOOGLE_ADS_LOGIN_CUSTOMER_ID=
Para producción con varias cuentas, agregá una allowlist explícita:
GOOGLE_ADS_MCP_ALLOWED_CUSTOMER_IDS=123-456-7890,987-654-3210
GOOGLE_ADS_MCP_REQUIRE_CUSTOMER_ALLOWLIST=true
No subas
.enva GitHub.
Paso 3 — Validar la instalación
Antes de abrir Claude:
python scripts/validate_local.py
La versión 0.17.0 debe terminar con:
LOCAL VALIDATION GREEN
validated version: 0.17.0
El gate ejecuta smoke aislado + Ruff + pytest completo. La referencia actual es 362/362 tests.
Si el import falla, verificá primero que estés usando el Python del venv:
.venv/bin/python -c "import google_ads_mcp; print(google_ads_mcp.__version__, google_ads_mcp.__file__)"
Paso 4 — Conectarlo a Claude Desktop / Claude Code
Usá la ruta absoluta al Python del venv, no un python genérico:
{
"mcpServers": {
"google-ads": {
"command": "/ruta/absoluta/MCP-Google-Ads/.venv/bin/python",
"args": ["-m", "google_ads_mcp.server"],
"env": {
"GOOGLE_ADS_MCP_ENV_FILE": "/ruta/absoluta/MCP-Google-Ads/.env"
}
}
}
}
Reiniciá el cliente MCP después de cambiar la configuración.
Guía de clientes: docs/CLIENTS.md.
Paso 5 — Primera prueba: sólo lectura
La primera vez, arrancá conservador:
GOOGLE_ADS_MCP_READ_ONLY=true
Y preguntá:
Listá mis customer IDs accesibles de Google Ads.
Después:
Mostrame performance por campaña de los últimos 7 días.
Si eso funciona, ya verificaste conexión, OAuth y acceso a Google Ads sin permitir mutaciones.
Paso 6 — Primera escritura segura
Cuando quieras probar escrituras:
GOOGLE_ADS_MCP_READ_ONLY=false
GOOGLE_ADS_MCP_AUTO_APPROVE=false
GOOGLE_ADS_MCP_AUTO_APPROVE_SPEND=false
GOOGLE_ADS_MCP_AUTO_APPROVE_DESTRUCTIVE=false
GOOGLE_ADS_MCP_AUTO_APPROVE_SENSITIVE=false
Pedile una modificación reversible:
Proponé renombrar esta campaña de prueba.
No confirmes el cambio.
Esperá una respuesta con:
status: pending_confirmation
pending_action_id: ...
Luego decidís:
Confirmá <pending_action_id>
O:
Cancelá <pending_action_id>
Seguridad de fábrica
Kill switch de sólo lectura
GOOGLE_ADS_MCP_READ_ONLY=true
Mantiene reporting, GAQL y auditoría, pero bloquea escrituras y confirmaciones.
Aislamiento MCC / customers
Una misma credencial MCC puede alcanzar muchas cuentas. El servidor valida customer IDs y referencias de recursos antes de contactar Google.
También filtra las superficies jerárquicas:
customer_clientcustomer_client_linkcustomer_manager_link
Y revisa referencias cross-customer incluso dentro de protobuf maps, Struct, listas y nested messages.
Niveles de riesgo
Acciones pendientes durables
Las propuestas viven en SQLite y sus argumentos de replay se cifran con Fernet.
GOOGLE_ADS_MCP_PENDING_ENCRYPTION_KEY=<fernet-key>
Si la clave falta o está corrupta, el sistema falla cerrado: no ejecuta la mutación.
Más detalle: docs/SAFETY.md.
Capacidades
Cobertura exhaustiva v25: docs/V25_SERVICE_COVERAGE.md.
Merchant Center (beta)
Además de Google Ads, el MCP puede hablar directo con Merchant API (el reemplazo de Content API for Shopping, que Google discontinuó en agosto 2026): estado de la cuenta, diagnóstico de productos rechazados/no elegibles, alta y baja de productos, gestión de feeds (data sources) y reporting vía MCQL — todo con el mismo modelo de propuesta/confirmación que el resto de las escrituras.
- Reutiliza el mismo cliente OAuth de Google Ads: generá el refresh token con
python -m google_ads_mcp.auth --generate-refresh-token --include-merchant-center(o seteáGOOGLE_MERCHANT_CENTER_REFRESH_TOKENaparte si Merchant Center vive en otra cuenta de Google). - Opcional:
GOOGLE_MERCHANT_CENTER_IDcomo cuenta por defecto. - Herramientas típicas:
list_merchant_center_product_issues(productos rechazados/no elegibles y por qué),get_merchant_center_product_performance,list_merchant_center_datasources,insert_merchant_center_product,remove_merchant_center_product.
Para agencias y consultores
Este proyecto nació para workflows donde marketing, datos y operación tienen que ocurrir juntos.
- Revisar una MCC sin saltar entre interfaces.
- Pasar de reporte a optimización en la misma conversación.
- Preparar campañas enteras y dejar todo PAUSED para revisión.
- Aplicar negativas desde Search Terms sin copiar/pegar.
- Investigar keywords con Keyword Planner desde Claude.
- Administrar conversiones, Customer Match, PMax y experiments.
- Tener trazabilidad de qué propuso la IA y qué aprobó una persona.
No reemplaza el criterio de un especialista. Le da al especialista más palanca.
¿Qué hace diferente a este proyecto?
El objetivo no es “darle control total a una IA”. El objetivo es darle herramientas reales a un operador humano asistido por IA.
Versión actual — 0.17.2
0.17.2 es la versión recomendada. Es un segundo patch fix, encontrado en re-testing en vivo inmediatamente después de desplegar 0.17.1: validate_only tenía el mismo bug que ya se había arreglado para partial_failure en mutate_atomic(), sin el mismo guardado defensivo. Detalle en docs/RELEASE_0.17.2.md. El fix de 0.17.1 sigue vigente y sin cambios; esto es la segunda mitad del mismo arreglo. Contexto original: 0.17.1 fue un patch fix sobre 0.17.0: corrige un bug de producción en mutate_atomic() que hacía fallar toda llamada atómica de creación+adjunto de asset (create_call_asset, create_sitelink_asset, create_message_asset, entre otras) con el error GoogleAdsServiceClient.mutate() got an unexpected keyword argument 'partial_failure'. Detalle completo en docs/RELEASE_0.17.1.md.
Todo lo que sigue abajo sobre 0.17.0 sigue vigente sin cambios — 0.17.1 no toca ninguna funcionalidad, solo corrige ese bug puntual.
0.17.0 sumó soporte para Google Merchant Center (beta) sobre la base 0.16.8, que sigue completa y sin cambios.
- Google Ads API v25.
- Merchant Center (beta): diagnóstico de cuenta, catálogo de productos, altas/bajas y feeds, vía Merchant API.
- Smoke aislado verde (56 módulos de tools).
- Ruff limpio.
- 362/362 pytest (16 nuevos de Merchant Center).
- Cero duplicate-tool warnings.
- Registro canónico de tools blindado por regresión.
- Google Ads sigue E2E validado contra una MCC real (read-only, aislamiento cross-customer, propose/cancel, propose/confirm, durable replay). Merchant Center todavía es solo local: unit tests + smoke, sin validar aún contra una cuenta real.
El detalle técnico de Merchant Center vive en docs/RELEASE_0.17.0.md. El release anterior, docs/RELEASE_0.16.8.md, sigue vigente para todo lo que no es Merchant Center.
Historial completo: CHANGELOG.md.
Actualizar una instalación existente
No reemplaces tu .env, audit DB ni encryption key.
cd MCP-Google-Ads
git fetch origin
git pull --ff-only origin main
source .venv/bin/activate
python -m pip install -e ".[dev]"
python scripts/validate_local.py
Procedimiento completo: docs/UPDATE_LOCAL.md.
Troubleshooting rápido
Guía completa: docs/SETUP.md#troubleshooting.
Documentación
Sobre Akela
Alejandro José · Akela
AI Products · WordPress Engineering · SEO Automation · Marketing Technology
Construyo software práctico donde se cruzan IA, marketing, publicidad, analytics, automatización y operación real.
Instagram @akelaonline · [email protected]
Build useful things. Ship them. Learn from production.
Si este proyecto te ahorra tiempo, una ⭐ al repo ayuda a que más gente lo encuentre.
Scope
Este MCP cubre Google Ads API, no todos los productos adyacentes de Google.
- Merchant Center feed/catalog editing corresponde a Merchant API.
- Google Business Profile es otra superficie.
- Servicios beta/allowlisted siguen requiriendo elegibilidad de Google.
ReservationServiceno es público y no se simula.
Contribuir
Contribuciones y issues son bienvenidos: CONTRIBUTING.md.
Regla principal: ninguna write tool debe saltarse la safety layer.
Licencia
MIT © 2026 Alejandro José · Akela. Ver LICENSE.