google-ads-mcp-coolify

Servidor MCP de Google Ads autoalojado para Coolify, Docker y cualquier VPS. Transporte HTTP transmisible con OAuth 2.0: conecta Claude Code, Cursor y cualquier cliente MCP con la API de Google Ads.

GitHubPrueba este MCPPatrocinado

Documentación

Servidor MCP de Google Ads — Autoalojado en Coolify (Docker, HTTP/SSE)

Implementa el Servidor MCP de Google Ads en tu propio VPS con Coolify en 5 minutos. Conecta Claude Code, Claude Desktop, Cursor o cualquier cliente del Protocolo de Contexto de Modelos a la API de Google Ads mediante OAuth 2.0 — a través de HTTPS, con un endpoint público.

Este repositorio es un envoltorio Docker listo para producción alrededor de gomarble-ai/google-ads-mcp-server que resuelve las dos piezas faltantes para la implementación remota:

Sin Dockerfile en el repositorio original → este repositorio añade uno.
El repositorio original funciona en modo stdio (solo funciona localmente con Claude Desktop) → este repositorio lo envuelve con transporte streamable-http para que pueda ser accesible a través de internet.

Perfecto para equipos que ejecutan infraestructura MCP autoalojada en plataformas como Coolify, Dokploy, EasyPanel, Railway, Render, Fly.io o cualquier configuración simple de Docker/Kubernetes.

Tabla de contenidos

¿Por qué autoalojar un servidor MCP de Google Ads?
Características
Cómo funciona
Inicio rápido (Coolify)
Inicio rápido (Docker simple)
Generación del archivo credentials.json de OAuth
Conexión desde Claude Code / Cursor / Claude Desktop
Herramientas MCP disponibles
Notas de seguridad
Solución de problemas
Contribuciones
Licencia

¿Por qué autoalojar un servidor MCP de Google Ads?

Privacidad: tus tokens OAuth de Google Ads nunca salen de tu infraestructura.
Multi-cliente: una instancia implementada sirve a Claude Code, Cursor, Continue, Zed, n8n y cualquier otra herramienta compatible con MCP.
Sin pasarela SaaS de pago: omite los relés MCP de terceros — ve directamente desde tu cliente de IA a tu VPS y luego a la API de Google Ads.
Funciona detrás de proxies inversos: HTTPS mediante Let's Encrypt, subdominio personalizado, middleware de autenticación opcional.

Características

✅ Transporte HTTP transmisible (especificación MCP) — funciona con todos los clientes MCP modernos
✅ OAuth 2.0 con renovación automática — sin rotación manual de tokens
✅ Autenticación Bearer token integrada (MCP_AUTH_TOKEN) — el endpoint nunca es accesible públicamente por defecto
✅ Credenciales mediante variables de entorno (GOOGLE_ADS_CREDENTIALS_JSON) — no se requiere montaje de archivos en Coolify
✅ Implementación en un solo subdominio — https://google-ads-mcp.yourdomain.com/mcp
✅ Soporte multi-cuenta / MCC mediante GOOGLE_ADS_LOGIN_CUSTOMER_ID
✅ Construido sobre FastMCP — rápido, asíncrono, de grado de producción
✅ Repositorio original actualizado: cada compilación obtiene el último gomarble-ai/google-ads-mcp-server de main
✅ Probado con Coolify — también funciona en Dokploy, EasyPanel, Railway, Fly.io, Docker simple

Cómo funciona

┌─────────────────┐       HTTPS         ┌────────────────────────┐       OAuth        ┌──────────────────┐
│  Claude Code /  │ ──── /mcp ─────────▶│  This container        │ ──── refresh ────▶ │  Google Ads API  │
│  Cursor / etc.  │                     │  (FastMCP HTTP server) │                    │  (v19)           │
└─────────────────┘                     └────────────────────────┘                    └──────────────────┘
                                                  │
                                                  ▼
                                        /app/credentials/credentials.json
                                        (mounted as a file by Coolify)

El contenedor hace tres cosas al iniciar:

Carga los tokens OAuth desde /app/credentials/credentials.json (montaje de archivos).
Importa la aplicación FastMCP definida en el server.py del repositorio original.
La ejecuta en 0.0.0.0:8000 usando transporte streamable-http.

Inicio rápido (Coolify)

1. Apunta un subdominio a tu VPS

Tipo	Nombre	Valor
A	`google-ads-mcp`	`<your VPS IP>`

2. Crea el recurso

Coolify → + Nuevo Recurso → Repositorio Público

Campo	Valor
Repositorio	`https://github.com/LuckSigog/google-ads-mcp-coolify`
Rama	`main`
Paquete de compilación	Dockerfile
Ubicación del Dockerfile	`/Dockerfile`
Puerto expuesto	`8000`
Dominio	`https://google-ads-mcp.yourdomain.com`

3. Variables de entorno

GOOGLE_ADS_DEVELOPER_TOKEN=<your_developer_token>
GOOGLE_ADS_AUTH_TYPE=oauth
PORT=8000

# Paste the full credentials.json content (single line is fine, JSON parser handles it)
GOOGLE_ADS_CREDENTIALS_JSON={"token":"ya29...","refresh_token":"1//0h...","token_uri":"https://oauth2.googleapis.com/token","client_id":"...","client_secret":"...","scopes":["https://www.googleapis.com/auth/adwords"]}

# Bearer token for endpoint auth (RECOMMENDED — without it, your endpoint is public)
# Generate with: python3 -c 'import secrets; print(secrets.token_urlsafe(32))'
MCP_AUTH_TOKEN=<long_random_string>

# Optional — only if you use a Manager (MCC) account:
# GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890

⚠️ No establezcas NODE_ENV ni ninguna variable de entorno no relacionada — Coolify inyecta todas las variables de entorno como ARGs de compilación, lo que puede romper compilaciones no relacionadas.

4. (Opcional) Monta las credenciales OAuth como archivo

Puedes omitir esto por completo si estableces GOOGLE_ADS_CREDENTIALS_JSON arriba. Usa un montaje de archivos solo si prefieres mantener el JSON fuera de las variables de entorno:

Coolify → Almacenamientos → + Añadir → Montaje de archivos

Ruta de montaje	Contenido
`/app/credentials/credentials.json`	Pega el JSON completo generado abajo

5. Implementa

Haz clic en Implementar. Cuando el contenedor esté saludable:

curl -i https://google-ads-mcp.yourdomain.com/mcp
# Expected: HTTP 200, 405, or similar — NOT 502

Inicio rápido (Docker simple)

docker build -t google-ads-mcp .

docker run -d \
  --name google-ads-mcp \
  -p 8000:8000 \
  -e GOOGLE_ADS_DEVELOPER_TOKEN=your_token \
  -e GOOGLE_ADS_AUTH_TYPE=oauth \
  -e GOOGLE_ADS_CREDENTIALS_PATH=/app/credentials/credentials.json \
  -v $(pwd)/credentials.json:/app/credentials/credentials.json:ro \
  google-ads-mcp

Generación del `credentials.json` de OAuth

Solo ejecutas esto una vez en tu máquina local para iniciar el token de actualización. El contenedor renovará automáticamente los tokens de acceso a partir de entonces.

Requisitos previos

Ve a Google Cloud Console
Crea un ID de cliente OAuth 2.0 de tipo Aplicación de escritorio
Descarga el archivo client_secret_*.json
Asegúrate de que la API de Google Ads esté habilitada en el proyecto
Ten un Token de desarrollador de Google Ads (solicítalo aquí)

Ejecuta el script de arranque

# gen_credentials.py
from google_auth_oauthlib.flow import InstalledAppFlow
import json, glob, sys

matches = glob.glob('client_secret*.json')
if not matches:
    sys.exit("Place a client_secret*.json next to this script first.")

flow = InstalledAppFlow.from_client_secrets_file(
    matches[0], scopes=['https://www.googleapis.com/auth/adwords'])
creds = flow.run_local_server(port=0)

with open('credentials.json', 'w') as f:
    json.dump({
        'token': creds.token,
        'refresh_token': creds.refresh_token,
        'token_uri': creds.token_uri,
        'client_id': creds.client_id,
        'client_secret': creds.client_secret,
        'scopes': creds.scopes,
    }, f, indent=2)
print("OK -> credentials.json generated")

python3 -m venv .venv && source .venv/bin/activate
pip install google-auth-oauthlib
python3 gen_credentials.py

Se abrirá un navegador. Inicia sesión con la cuenta de Google que tenga acceso a tu cuenta de Google Ads y autoriza. Obtendrás un credentials.json en el directorio actual.

Sube ese JSON como montaje de archivos en Coolify (paso 4 arriba).

Conexión desde Claude Code / Cursor / Claude Desktop

Claude Code (CLI)

Si estableces MCP_AUTH_TOKEN:

claude mcp add --transport http google-ads https://google-ads-mcp.yourdomain.com/mcp \
  --header "Authorization: Bearer YOUR_MCP_AUTH_TOKEN" --scope user
claude mcp list

Sin autenticación:

claude mcp add --transport http google-ads https://google-ads-mcp.yourdomain.com/mcp --scope user

Pruébalo:

"List my Google Ads accounts"

Cursor / Continue / Zed

Añade a tu configuración de servidores MCP:

{
  "mcpServers": {
    "google-ads": {
      "type": "http",
      "url": "https://google-ads-mcp.yourdomain.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN"
      }
    }
  }
}

Claude Desktop (solo stdio local)

Claude Desktop no habla HTTP MCP. Si lo quieres allí, instala el gomarble-ai/google-ads-mcp-server del repositorio original directamente en tu máquina.

Herramientas MCP disponibles

Heredadas del repositorio original:

Herramienta	Descripción
`list_accounts`	Lista todas las cuentas de Google Ads accesibles, incluidas las subcuentas anidadas bajo MCC
`run_gaql`	Ejecuta cualquier consulta del Lenguaje de Consulta de Google Ads (GAQL) — campañas, grupos de anuncios, palabras clave, conversiones, informes
`run_keyword_planner`	Genera ideas de palabras clave con volumen de búsqueda, competencia y rango de oferta de CPC

La referencia GAQL se expone como un recurso MCP: gaql://reference.

Notas de seguridad

Este envoltorio incluye autenticación Bearer token integrada (variable de entorno MCP_AUTH_TOKEN). Establécelo y el endpoint requerirá Authorization: Bearer <token> en cada solicitud — sin token, sin acceso.

Genera un token fuerte:

python3 -c 'import secrets; print(secrets.token_urlsafe(32))'
# or:
openssl rand -base64 32

Para implementaciones de equipo, vale la pena considerar un endurecimiento adicional:

Tokens por usuario con revocación — respalda el middleware con una tabla de hashes de tokens en Supabase/Postgres (planificado en una versión futura; se aceptan PRs)
Cloudflare Access / Tailscale / WireGuard — SSO de confianza cero frente al endpoint
Lista de IP permitidas en la capa de Coolify/Cloudflare si te conectas desde un conjunto fijo de máquinas

Incluso con MCP_AUTH_TOKEN, trata el endpoint como un límite de defensa en profundidad, no como la única línea de defensa — rota el token periódicamente.

Solución de problemas

`sh: tsc: not found` o la compilación falla con devDependencies faltantes

Estás encontrando la peculiaridad de Coolify de variables de entorno como ARG de compilación. No establezcas NODE_ENV=production como variable de entorno en el servicio de Coolify. Eso se inyecta como ARG de compilación y rompe Dockerfiles no relacionados. (Este repositorio es Python, pero el mismo patrón afecta a servidores MCP basados en Node.)

`ERROR: failed to read dockerfile`

Verifica Directorio base = / y Ubicación del Dockerfile = /Dockerfile en la pestaña de Configuración de Coolify.

`401 Unauthorized` / `OAuth credentials expired`

Abre credentials.json y confirma que refresh_token está presente. Si falta, regenéralo mediante gen_credentials.py y vuelve a subir el montaje de archivos.

`Developer token is not approved`

Un token de desarrollador nuevo tiene acceso limitado (solo cuentas de prueba). Para cuentas de producción, solicita Acceso Básico en el Centro de API de Google Ads.

`LOGIN_CUSTOMER_ID required`

Estás consultando a través de una cuenta de administrador (MCC). Establece GOOGLE_ADS_LOGIN_CUSTOMER_ID=<mcc_id_without_dashes> y vuelve a implementar.

`502 Bad Gateway` después de la implementación

El contenedor se inició pero no está escuchando en el puerto 8000. Revisa los registros de compilación — la mayoría de las veces el git clone del repositorio original falló. Vuelve a activar la implementación.

Contribuciones

Se aceptan PRs. Específicamente útiles:

Middleware de autenticación opcional (Bearer / Basic / lista de IP permitidas)
Opción de SHA fijo del repositorio original (actualmente compila contra main)
Gráfico Helm / manifiestos de Kubernetes
Ejemplos para integraciones MCP de n8n, Make, Zapier

Licencia

MIT — misma licencia que el proyecto gomarble del repositorio original.

Créditos

Servidor MCP del repositorio original: gomarble-ai/google-ads-mcp-server
Protocolo de Contexto de Modelos: modelcontextprotocol.io
Coolify: coolify.io
FastMCP: jlowin/fastmcp

Palabras clave: servidor mcp google ads, google ads mcp coolify, mcp google ads autoalojado, servidor mcp docker, implementar servidor mcp vps, integración google ads claude code, servidor http fastmcp, api google ads claude, mcp http transmisible, protocolo de contexto de modelos google ads, cursor google ads mcp, n8n google ads mcp, autoalojar protocolo de contexto de modelos, google ads oauth mcp.