<div align="center">

🌐 Elegí tu idioma / Choose your language

🇦🇷🇪🇸 Español · 🇬🇧🇺🇸 English

<br> <img src="https://avatars.githubusercontent.com/u/76195052?v=4" width="96" alt="Alejandro José · Akela" />

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

<br>

Qué problema resuelve · Cómo funciona · Tutorial paso a paso · Ejemplos · Seguridad · Capacidades · Sobre Akela

</div>

---

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

| Necesidad | Qué aporta este MCP | |---|---| | Muchas cuentas | MCC + allowlist + aislamiento entre customers | | Optimización diaria | Reportes → decisión → acción dentro de la misma conversación | | Cambios delicados | propose → preview → confirm → execute → audit | | Auditoría | SQLite local con historial y action IDs | | Reinicios | Acciones pendientes durables y cifradas | | Reporting-only | Kill switch GOOGLE_ADS_MCP_READ_ONLY=true | | Integración con IA | Claude Desktop, Claude Code o cualquier cliente MCP compatible |

---

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 .env a 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_client
• customer_client_link
• customer_manager_link

Y revisa referencias cross-customer incluso dentro de protobuf maps, Struct, listas y nested messages.

Niveles de riesgo

| Clase | Ejemplos | Comportamiento recomendado | |---|---|---| | standard | preparación/administración sin delivery inmediato | confirmación humana | | spend | presupuesto, puja, keywords, targeting, assets live | confirmación humana obligatoria | | destructive | remove/unlink | confirmación humana obligatoria | | sensitive | acceso, billing, Customer Match, links | confirmación humana obligatoria |

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

| Área | Cobertura | |---|---| | Cuentas y MCC | discovery, jerarquía, vínculos manager/cliente, usuarios, roles, invitaciones | | Reporting | campañas, ad groups, ads, keywords, search terms, dispositivos, geo, assets, audiencias, shopping, impression share, change history, GAQL | | Campañas | Search, Standard Shopping, Performance Max, Demand Gen, App Campaigns, Dynamic Search Ads, Smart Campaigns | | Presupuestos y bidding | budgets, Manual CPC, Max Clicks/Conversions/Value, Target CPA/ROAS/Impression Share, portfolio bidding | | Ads y assets | RSA, Responsive Display, Demand Gen, imágenes, video, calls, sitelinks, callouts, snippets, promociones, WhatsApp, lead forms, price, location, app/deep link | | Keywords y targeting | ciclo de vida, bids, match types, negativas, location/language/device/audience/topic, placements, schedules, tracking URLs | | Audiencias | remarketing, UserList, Customer Match, Audience, CustomAudience, CustomInterest | | Conversiones y goals | actions, offline/call/enhanced uploads, GDPR consent, adjustments, value rules, unified goals | | Performance Max | campaign + asset groups + assets + signals + listing filters + previews | | Experiments | lifecycle, arms, schedule, promote, graduate, end, traffic splits | | Batch / Smart Bidding | Batch Jobs, seasonality adjustments, data exclusions | | Billing y links | billing setup, invoices, account budgets, ProductLink, DataLink, YouTube/app analytics | | Planning / especialistas | Keyword Planner, Reach Planner, Local Services,