gsc-mcp-connector

Servidor MCP de Google Search Console autoalojado, desplegable en Cloudflare Workers en 15 minutos. Conéctalo a ChatGPT, Claude o cualquier cliente compatible con MCP y consulta tus datos de GSC en lenguaje natural.

Lo que te ofrece

Una vez desplegado, obtienes un endpoint MCP privado que expone 4 herramientas a tu asistente de IA:

• list_sites — descubre cada propiedad accesible para el usuario autenticado

• query_search_analytics — clics, impresiones, CTR, posición, filtrable por consulta / página / país / dispositivo / apariencia de búsqueda / fecha

• inspect_url — salida completa de la API de Inspección de URL (estado de indexación, canónica, móvil, AMP)

• list_sitemaps — cada sitemap enviado y su estado de procesamiento

Preguntas: "¿Cuáles son mis 50 consultas con mayor pérdida de clics entre los últimos 28 días y los 28 días anteriores?" y el asistente obtiene los datos, calcula la diferencia y escribe el análisis. Sin más exportaciones SQL.

Related MCP server: gsc-mcp-connector

Cómo funciona

ChatGPT/Claude  ──OAuth──▶  Your Worker  ──OAuth──▶  Google
                                 │
                                 └─ holds your Google refresh_token
                                    (encrypted, in OAuth grant props)

Dos cadenas OAuth:

1. Cliente MCP → Worker: ChatGPT/Claude realizan OAuth 2.1 + PKCE contra tu Worker. La interfaz de inicio de sesión solicita una "clave de acceso" estática que configuras al desplegar (la puerta del conector).

2. Worker → Google: después de verificar la clave de acceso, el usuario es redirigido a la pantalla de consentimiento de Google para otorgar webmasters.readonly. El token de actualización resultante se almacena en la concesión OAuth; en cada llamada de herramienta, el Worker renueva un token de acceso fresco y llama a GSC.

La cuenta de Google del usuario impulsa el acceso — sin cuenta de servicio, sin gestiones de usuarios de GSC, sin retrasos en la propagación de permisos.

Requisitos previos

El nivel gratuito de Cloudflare Workers (100k solicitudes/día) es más que suficiente para uso SEO personal. No se necesita un plan de Cloudflare de pago.

Inicio rápido (~15 min)

1. Desplegar el Worker

Haz clic en el botón Desplegar en Cloudflare al inicio de este README. Cloudflare clona el repositorio en tu cuenta, instala las dependencias y te da una URL pública como https://gsc-mcp-connector.<tu-subdominio>.workers.dev.

Nota: en esta etapa, se te pedirá MCP_BEARER_TOKEN, GOOGLE_OAUTH_CLIENT_ID y GOOGLE_OAUTH_CLIENT_SECRET. Aún no tienes los de Google — completa MCP_BEARER_TOKEN con cualquier cadena hexadecimal aleatoria por ahora (puedes cambiarlo después) y pega cualquier cosa en los dos campos de Google. Los configuraremos correctamente en el paso 4.

Si prefieres omitir el botón, clona el repositorio localmente, ejecuta npm install y luego npx wrangler deploy.

Después del despliegue, anota la URL de tu Worker. La necesitarás tanto en el paso 3 como en el paso 5.

2. Generar una clave de acceso del conector

Esta es una cadena aleatoria estática que sirve como puerta antes de OAuth de Google. Cualquier persona que use el conector debe pegar esta cadena en la interfaz de inicio de sesión.

openssl rand -hex 32

Guarda la salida — la configurarás como secreto y la usarás en ChatGPT/Claude.

3. Configurar Google Cloud (Cliente OAuth)

Sigue los pasos detallados en docs/SETUP_GCP.md. Usa la URL de tu Worker del paso 1 en la URI de redirección autorizada. Obtendrás un ID de cliente y un Secreto de cliente.

Este es el paso más largo (~10 min la primera vez) pero solo lo haces una vez.

4. Configurar los secretos del Worker

npx wrangler secret put MCP_BEARER_TOKEN
# paste the value from step 2

npx wrangler secret put GOOGLE_OAUTH_CLIENT_ID
# paste the Client ID from step 3

npx wrangler secret put GOOGLE_OAUTH_CLIENT_SECRET
# paste the Client Secret from step 3

O a través del panel de Cloudflare: Workers & Pages → tu worker → Configuración → Variables y secretos → añade cada uno como tipo Secreto.

Consejo — problema de codificación en Windows: si canalizas el contenido de un archivo (ej. Get-Content | wrangler secret put) y ese archivo tiene un BOM UTF-8, el BOM termina en tu secreto y rompe el análisis JSON. El panel de Cloudflare o wrangler secret put interactivo (pegar en el aviso) evita esto por completo.

5. Conectar a ChatGPT (Plus/Pro/Team)

ChatGPT → Configuración → Conectores → Añadir conector personalizado:

• Nombre: gsc

• URL del servidor MCP: https://TU-WORKER-URL/mcp (debe terminar en /mcp)

• Autenticación: OAuth

• Marca "Entiendo y quiero continuar"

• Crear

Se abre una ventana emergente con la interfaz de inicio de sesión de tu Worker. Pega tu MCP_BEARER_TOKEN → haz clic en Continuar con Google → Google te pide que inicies sesión (usa la cuenta que posee tu propiedad de GSC) y otorgues webmasters.readonly → eres redirigido de vuelta a ChatGPT, el conector está activo.

En un nuevo chat, activa el conector gsc en la barra de herramientas, luego pregunta: "Lista mis sitios de Google Search Console". Deberías ver tus propiedades.

6. (Opcional) Conectar a Claude.ai (Pro/Team)

Configuración → Integraciones → Añadir integración personalizada → misma URL, mismo flujo.

Desarrollo local

git clone https://github.com/JuJu78/gsc-mcp-connector
cd gsc-mcp-connector
npm install
cp .dev.vars.example .dev.vars
# edit .dev.vars with your real Client ID + Client Secret + bearer token
npx wrangler dev

El servidor de desarrollo se ejecuta en http://localhost:8787. Ten en cuenta que el desarrollo local no puede completar completamente el flujo OAuth de Google porque las URI de redirección de Google requieren HTTPS. Para una prueba completa de extremo a extremo, despliega en Cloudflare y prueba contra la URL de workers.dev.

Limitaciones

• Solo lectura. Agregar operaciones de escritura (enviar sitemap, solicitar indexación) se omite por diseño: son riesgosas en un contexto de LLM. Abre un PR si las necesitas.

• Diseñado para un solo inquilino. Un operador despliega, un token de portador protege el conector, el acceso está vinculado a quien completa el flujo OAuth de Google. El estilo multi-usuario tipo SaaS está fuera del alcance.

• Consentimiento OAuth en modo Prueba te limita a 100 usuarios de prueba (más que suficiente para uso personal/equipo). Para una distribución más amplia, necesitarías enviar la aplicación para verificación de Google (webmasters.readonly es un ámbito "sensible", requiere revisión manual).

• Cuotas de la API de GSC — 1200 consultas/min/proyecto, 30k/día. Suficiente para uso interactivo.

• Rango de fechas — GSC devuelve los últimos 16 meses. Fechas anteriores dan error.

Solución de problemas

Stack

• Cloudflare Workers + Durable Objects (a través del SDK agents ≥0.12)

• @cloudflare/workers-oauth-provider para OAuth 2.1 + DCR + PKCE

• @modelcontextprotocol/sdk para definiciones de herramientas

• Espacio de nombres KV OAUTH_KV para estado OAuth

• Flujo OAuth 2.0 de Google firmado de forma nativa mediante Web Crypto API (sin dependencias de Node)

Créditos

Construido por Julien Gourdon — consultor SEO explorando la intersección entre búsqueda e IA.

Licencia

MIT — consulta LICENSE.