Google Ads MCP

Servidor Google Ads MCP

Un servidor MCP local para leer y escribir la API de Google Ads. Gestión completa de campañas con un flujo de seguridad de prueba/confirmación en cada escritura.

Requisitos previos

1. Cuenta de Google Ads Manager (MCC) con un token de desarrollador. Comprueba su nivel de acceso: Interfaz de Google Ads -> Herramientas y ajustes -> Configuración -> Centro de API.
   • Prueba: solo puede llamar a cuentas de prueba. Solicita acceso Básico para tocar cuentas en vivo (la aprobación puede tardar unos días).
   • Básico/Estándar: listo para cuentas en vivo.
2. Un proyecto de Google Cloud con la API de Google Ads habilitada y un cliente OAuth2 de tipo Aplicación de escritorio (te proporciona un ID de cliente y un secreto de cliente).

Configuración

python -m venv .venv
. .venv/Scripts/activate      # Windows PowerShell: .venv\Scripts\Activate.ps1
pip install -e ".[dev]"

# Mint a refresh token (one-off browser consent):
python scripts/generate_refresh_token.py --client-id XXX --client-secret YYY

cp .env.example .env          # then fill in every value

Si tu pantalla de consentimiento de OAuth sigue en modo prueba, añade primero la cuenta de Google con la que inicias sesión como usuario de prueba (Consola de Cloud -> APIs y servicios -> Pantalla de consentimiento de OAuth -> Público); de lo contrario, el consentimiento falla con un error de verificación.

Una vez que .env contiene el ID y el secreto de cliente, python scripts/remint_refresh_token.py vuelve a emitir un token de actualización caducado o revocado y reescribe .env en su lugar, sin imprimir el secreto.

Nunca hagas commit de .env; está en gitignore, y es el único lugar donde las credenciales reales deberían vivir.

Claves de .env: GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, GOOGLE_ADS_REFRESH_TOKEN, GOOGLE_ADS_LOGIN_CUSTOMER_ID (tu ID de MCC, los guiones son opcionales, se muestra arriba a la derecha en la interfaz de Google Ads cuando inicias sesión en la cuenta de administrador).

Ejecutar las pruebas

pip install -e ".[dev]"
pytest -v

Registrar con Claude Code

Usa la ruta absoluta de Python del venv para que el registro funcione independientemente del directorio desde el que se lance Claude Code (el servidor también resuelve .env desde la raíz del proyecto, no desde el directorio de trabajo actual):

# Windows
claude mcp add google-ads -- "<REPO_PATH>\.venv\Scripts\python.exe" -m google_ads_mcp.server

# macOS / Linux
claude mcp add google-ads -- "<REPO_PATH>/.venv/bin/python" -m google_ads_mcp.server

Añade --scope user para que las herramientas estén disponibles en todos los proyectos en lugar de solo en este.

Seguridad en las escrituras

Cada herramienta de escritura usa por defecto una vista previa: valida el cambio con el validate_only de la API y devuelve un confirmation_token. Para aplicar, llama a la misma herramienta de nuevo con commit=true y ese token. La operación confirmada es byte por byte lo que se previsualizó. Nada gasta dinero hasta que confirmes.

Herramientas

Lectura: list_accounts, run_gaql, get_campaigns, get_ad_groups, get_keywords, get_performance.

Escritura (vista previa -> confirmación): create_campaign_budget, create_campaign, update_budget, update_campaign_status, create_ad_group, update_ad_group_status, create_responsive_search_ad, add_keywords, add_negative_keywords, apply_mutate.