google-ads-mcp

Servidor MCP (Model Context Protocol) para gestionar Google Ads y Google Analytics 4 directamente desde Claude Code y Claude Desktop.

Escrito por Gabriel Urrutia. Inspirado en AdLoop por kLOsk — reimplementación independiente optimizada para Claude con soporte nativo en Windows, macOS y Linux.

¿Qué hace?

• Analizar rendimiento de campañas, anuncios y keywords
• Consultar términos de búsqueda y proponer negativos
• Pausar / activar campañas, grupos y anuncios
• Crear anuncios de búsqueda responsivos (RSA)
• Agregar negative keywords
• Ejecutar queries GAQL personalizadas
• Consultar reportes y usuarios en tiempo real de GA4

Todo con un sistema de seguridad preview → confirm: ningún cambio se aplica sin aprobación explícita.

Requisitos

• Python 3.11+
• uv (gestor de paquetes)
• Cuenta de Google Ads con acceso a la API
• Google Cloud Project con las APIs habilitadas

Instalación

Windows (PowerShell)

git clone https://github.com/gabogabucho/google-ads-mcp.git
cd google-ads-mcp
powershell -ExecutionPolicy Bypass -File install.ps1

macOS / Linux (bash)

git clone https://github.com/gabogabucho/google-ads-mcp.git
cd google-ads-mcp
bash install.sh

Los instaladores:

1. Verifican Python, uv y git
2. Crean el virtualenv e instalan dependencias
3. Crean ~/.google-ads-mcp/config.yaml desde el ejemplo
4. Copian las Skills a ~/.claude/skills/
5. Muestran el snippet exacto para configurar Claude Desktop

Configuración de Google

1. Google Cloud Project

1. Ve a console.cloud.google.com → crea un proyecto
2. Habilita estas APIs:
   • Google Ads API
   • Google Analytics Data API
   • Google Analytics Admin API

2. Credenciales OAuth 2.0

1. APIs & Services → Credentials → Create → OAuth 2.0 Client ID
2. Application type: Desktop app
3. Descarga el JSON → guárdalo como ~/.google-ads-mcp/credentials.json

3. Developer Token de Google Ads

• En Google Ads: herramienta (llave inglesa) → API Center → copia el token
• El token de nivel TEST solo funciona con cuentas de prueba

4. Editar config.yaml

# macOS/Linux
$EDITOR ~/.google-ads-mcp/config.yaml

# Windows
notepad %USERPROFILE%\.google-ads-mcp\config.yaml

Ver config/config.yaml.example para todos los campos.

5. Primera autenticación

El primer python -m google_ads_mcp abre el navegador para autenticar con Google. El token se guarda en ~/.google-ads-mcp/token.json y se renueva automáticamente.

Configurar en Claude Desktop

Edita claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "google-ads": {
      "command": "RUTA_AL_PYTHON_DEL_VENV",
      "args": ["-m", "google_ads_mcp"],
      "env": {
        "GOOGLE_ADS_MCP_CONFIG": "RUTA_A_CONFIG_YAML"
      }
    }
  }
}

El instalador muestra las rutas exactas para tu sistema al terminar.

Configurar en Claude Code

# Añadir globalmente
claude mcp add google-ads \
  --env GOOGLE_ADS_MCP_CONFIG=$HOME/.google-ads-mcp/config.yaml \
  -- python -m google_ads_mcp

O crea .mcp.json en la raíz del proyecto (ver config/mcp.json.example).

Skills disponibles

Después de instalar, usa estos comandos en Claude Code:

Herramientas MCP

Lectura — Google Ads

Lectura — GA4

Escritura (preview → confirm)

Sistema de seguridad

Usuario pide cambio
    ↓
preview_*()  →  valida límites, genera plan con ID corto
    ↓
Claude muestra preview, pide confirmación
    ↓
apply_change(plan_id, dry_run=True)   ← simulación primero
    ↓
apply_change(plan_id, dry_run=False)  ← solo con OK explícito del usuario

Protecciones activas:

• Cap de presupuesto diario máximo (configurable)
• Límite de % de aumento de bids
• Operaciones bloqueadas por lista
• Log de auditoría en ~/.google-ads-mcp/audit.log
• RSAs nuevos creados en estado PAUSED

Estructura del proyecto

google-ads-mcp/
├── src/google_ads_mcp/
│   ├── server.py       # FastMCP: definición de todas las tools
│   ├── ads.py          # Google Ads API (lectura y escritura)
│   ├── ga4.py          # Google Analytics 4 API (solo lectura)
│   ├── auth.py         # OAuth 2.0 con token caching
│   ├── config.py       # Carga de config.yaml
│   └── safety.py       # Guards, plan store, audit log
├── skills/
│   ├── google-ads-analyze/SKILL.md
│   ├── google-ads-manage/SKILL.md
│   ├── google-ads-ga4/SKILL.md
│   └── google-ads-setup/SKILL.md
├── config/
│   ├── config.yaml.example
│   ├── claude-desktop-config.json.example
│   └── mcp.json.example
├── docs/troubleshooting.md
├── install.sh          # macOS / Linux
├── install.ps1         # Windows PowerShell
├── pyproject.toml
└── LICENSE             # MIT

Créditos

• Gabriel Urrutia (@gabogabucho) — autor
• Inspirado en AdLoop por kLOsk

MIT License — ver LICENSE.