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.

Qué te ofrece esto

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

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

Related MCP server: Google Search Console MCP

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 en el momento del despliegue (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 a la 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 baile de gestión de usuarios de GSC, sin demoras de propagación de permisos.

Prerrequisitos

El plan gratuito de Cloudflare Workers (100k solicitudes/día) es suficiente para uso SEO personal. No se necesita ningún plan pago de Cloudflare.

Inicio rápido (~15 min)

1. Desplegar el Worker

Haz clic en el botón Deploy to Cloudflare en la parte superior 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án 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 cambiarla 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, 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 la autenticación 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 la guía paso a paso 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 → Settings → Variables and Secrets → agrega cada uno como tipo Secret.

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

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

ChatGPT → Settings → Connectors → Add custom connector:

• Name: gsc

• MCP Server URL: https://YOUR-WORKER-URL/mcp (debe terminar con /mcp)

• Authentication: OAuth

• Marca "I understand and want to continue"

• Create

Aparece una ventana emergente que lleva a la interfaz de inicio de sesión de tu Worker. Pega tu MCP_BEARER_TOKEN → haz clic en Continue with 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)

Settings → Integrations → Add custom integration → 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.

• Inquilino único por diseño. Un operador despliega, una clave de acceso protege el conector, el acceso está vinculado a quien complete el flujo OAuth de Google. El estilo multi-usuario 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 API de GSC — 1200 consultas/min/proyecto, 30k/día. Suficiente para uso interactivo.

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

Solución de problemas

Pila tecnológica

• 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 — ver LICENSE.