Google Search Console MCP

Un servidor MCP para la API de Google Search Console: datos de rendimiento de búsqueda, estado de indexación de URL, gestión de sitemaps y listado de propiedades.

Se ejecuta de tres formas desde una misma base de código: stdio (local, mediante npx), Streamable HTTP (autohospedado) y Cloudflare Workers (alojado en una URL). Implementa MCP 2026-07-28 con retroceso automático a 2025-11-25, 2025-06-18 y 2025-03-26, por lo que funciona con clientes de cualquiera de las dos eras del protocolo.

Cero dependencias de ejecución.

Inicio rápido

npx google-search-console-mcp auth

Te guía por la creación de un cliente OAuth de Google, ejecuta el flujo de consentimiento, verifica las credenciales contra la API en vivo e imprime un bloque de configuración listo para pegar en tu cliente MCP. Tres minutos, la mayoría esperando a la interfaz de Google Cloud.

Luego pega el JSON resultante en la configuración de tu cliente y reinícialo.

Related MCP server: searchconsole-mcp

Herramientas

Todos los métodos de la API de Search Console v1, más dos compuestos.

La verificación de sitios y sites.add/sites.delete se omiten deliberadamente: añadir y verificar propiedades es un flujo de navegador que no pertenece a una herramienta de agente.

El servidor también ofrece prompts (performance_review, indexing_audit, query_opportunities, sitemap_health) y recursos (gsc://guide/search-analytics, gsc://guide/url-inspection, gsc://guide/sitemaps) que los agentes pueden leer bajo demanda.

Autenticación

Paso 1: crea un cliente OAuth de Google

Solo lo haces una vez. El servidor no puede hacerlo por ti: Google requiere una persona en su consola.

1. Abre la Consola de Google Cloud y selecciona o crea un proyecto.

2. Habilita la API de Search Console para ese proyecto.

3. Configura la pantalla de consentimiento de OAuth. Externa es suficiente para uso personal. Añade tu propia cuenta de Google en Usuarios de prueba.

4. Ve a Credenciales → Crear credenciales → ID de cliente de OAuth. Elige el tipo de aplicación Aplicación de escritorio.

5. Copia el ID de cliente y el secreto de cliente.

Pruebas vs. Publicado. Mientras la pantalla de consentimiento esté en Pruebas, Google caduca los tokens de actualización después de 7 días y tendrás que volver a ejecutar auth semanalmente. Publicar la aplicación (pantalla de consentimiento → Publicar aplicación) hace que sean duraderos. Para una herramienta interna de un solo usuario, publicarla es seguro y no requiere la revisión de verificación de Google siempre que te ciñas a los ámbitos de webmasters.

Paso 2: ejecuta el flujo de configuración

npx google-search-console-mcp auth

Esto abre una pequeña página de configuración servida desde 127.0.0.1. Pega el ID de cliente y el secreto, elige acceso completo o de solo lectura, y ejecuta el flujo de consentimiento, intercambia el código (con PKCE) por un token de actualización y llama a list_sites para demostrar que las credenciales funcionan, mostrándote las propiedades exactas a las que pueden acceder.

La página final te da el blob de credenciales y la configuración lista para pegar para Claude Desktop, Claude Code e implementaciones remotas, cada una con un botón de copiar. Los mismos valores se imprimen en tu terminal como alternativa.

En una máquina sin interfaz gráfica o mediante SSH, usa auth --terminal para la versión guiada por terminal.

Recibes un blob de credenciales: JSON codificado en base64url que contiene tu ID de cliente, secreto de cliente y token de actualización:

eyJ2IjoxLCJjcmVkZW50aWFscyI6eyJ0eXBlIjoib2F1dGhfcmVmcmVzaF90b2tlbiIsImNsaWVu…

Trata el blob como una contraseña. Cualquiera que lo tenga tiene acceso a tu Search Console hasta que lo revoques en myaccount.google.com/permissions.

Existe como una única cadena opaca para que un solo valor transporte todo lo que el servidor necesita: se inserta directamente en una variable de entorno o en una cabecera Authorization sin necesidad de un archivo de credenciales en disco.

Alternativas al flujo de OAuth

Cuenta de servicio. Útil para CI y para propiedades de equipo. Crea una en Google Cloud y luego añade su client_email como usuario de la propiedad en Search Console (Configuración → Usuarios y permisos). Codifica el archivo de clave descargado directamente:

base64 -i service-account.json | tr -d '\n'

El servidor acepta una clave de cuenta de servicio sin procesar como blob: no se necesita ningún envoltorio.

Token de acceso existente. Establece {"type":"access_token","access_token":"ya29..."}. No es posible renovarlo, por lo que solo sirve para scripts de corta duración.

Ámbitos

Elegir solo lectura durante auth solicita el ámbito más restringido. --read-only en el servidor es una salvaguarda adicional que rechaza las herramientas de mutación antes de que lleguen a la API.

Ejecución

Local (stdio)

La configuración que imprime auth:

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "google-search-console-mcp"],
      "env": { "GSC_CREDENTIALS": "<your blob>" }
    }
  }
}

Ubicaciones de los archivos de configuración:

Instálalo correctamente si prefieres no pasar por npx cada vez:

npm install -g google-search-console-mcp

HTTP autohospedado

GSC_CREDENTIALS=<blob> npx google-search-console-mcp http --port 8787

Sirve POST http://127.0.0.1:8787/mcp. Se vincula a loopback de forma predeterminada: pasa --host 0.0.0.0 deliberadamente si quieres exponerlo, y coloca TLS delante si lo haces.

Los clientes de navegador se rechazan a menos que los nombres, porque un servidor que guarda sus propias credenciales podría ser utilizado por cualquier página que visites. Los clientes MCP normales no envían Origin y no se ven afectados; un navegador necesita que su origen esté en la lista:

npx google-search-console-mcp http --allowed-origins http://localhost:6274   # MCP Inspector

Un origen rechazado recibe un 403 que el navegador no puede leer (sin cabeceras CORS en una denegación, por diseño), por lo que se manifiesta como un fallo CORS genérico: revisa la línea Origins: de arranque del servidor si un cliente de navegador no puede conectarse. --allowed-origins '*' desactiva la comprobación.

Cloudflare Workers

git clone https://github.com/russjeffery/google-search-console-mcp.git
cd google-search-console-mcp
npm install
npx wrangler deploy

Tu endpoint es https://google-search-console-mcp.<subdomain>.workers.dev/mcp.

De forma predeterminada, el Worker no almacena secretos. Cada cliente envía su propio blob de credenciales como token de portador, por lo que una implementación compartida nunca guarda las credenciales de Google de nadie, y diferentes usuarios de la misma URL solo ven sus propias propiedades.

Para una implementación privada de un solo inquilino, en su lugar:

npx wrangler secret put GSC_CREDENTIALS     # your blob
npx wrangler secret put MCP_SHARED_SECRET   # token clients must present

Los clientes envían entonces el secreto compartido en lugar de un blob.

vars opcionales en wrangler.jsonc:

Conexión de un cliente al servidor remoto

{
  "mcpServers": {
    "google-search-console": {
      "type": "http",
      "url": "https://your-worker.workers.dev/mcp",
      "headers": { "Authorization": "Bearer <your blob>" }
    }
  }
}

En la interfaz web o de escritorio de Claude, añádelo en Configuración → Conectores → Añadir conector personalizado.

Imprime esto rellenado para tu propia implementación:

npx google-search-console-mcp config --url https://your-worker.workers.dev/mcp

CLI

google-search-console-mcp [command] [options]

  stdio     Run as a stdio MCP server (default)
  http      Run a local Streamable HTTP MCP server
  auth      Guided setup in your browser: OAuth flow, blob, client config
  config    Print client config for existing credentials
  doctor    Verify credentials by calling the API

doctor es lo primero a lo que recurrir cuando algo no funciona: separa "las credenciales son incorrectas" de "el cliente no puede iniciar el servidor".

Opciones: --credentials <blob>, --site <siteUrl>, --read-only, --port, --host, --endpoint, --secret, --allowed-origins, --url, --terminal, --no-browser.

--allowed-origins acepta una lista separada por comas; sin definir significa solo clientes no navegador. Las entradas se comparan sin distinguir mayúsculas de minúsculas y se ignora una barra final.

--site establece una propiedad predeterminada para que las herramientas puedan omitir siteUrl, algo práctico cuando una implementación solo cubre un sitio.

Soporte de protocolo

La revisión de 2026-07-28 cambió sustancialmente Streamable HTTP: sin handshake de initialize, sin sesiones, sin Mcp-Session-Id, sin flujo GET, y metadatos por solicitud en params._meta reflejados en cabeceras HTTP. El SDK oficial de TypeScript aún no lo implementa, por lo que la capa de protocolo aquí está escrita a mano y es de doble era.

La era se detecta por solicitud: una solicitud con _meta moderno se atiende como moderna, un initialize selecciona la heredada. GET y DELETE en el endpoint devuelven 405, como prescribe la revisión.

La validación de cabeceras es estricta de forma predeterminada, según la especificación. Si un cliente envía _meta moderno sin reflejar las cabeceras, establece MCP_STRICT_HEADERS=0 (o --loose-headers) en lugar de degradar la versión.

Sobre la autorización: el flujo OAuth 2.1 de la especificación asume que el servidor es un servidor de recursos con su propio servidor de autorización. Este servidor, en cambio, usa el token de portador para transportar tus credenciales de Google directamente — la especificación permite estrategias personalizadas, y esto significa que un despliegue alojado no guarda secretos ni necesita una base de datos de usuarios. La contrapartida es que los clientes que esperan descubrimiento automático de OAuth necesitarán configurar la cabecera manualmente, como se muestra arriba.

Trabajar con los datos

Cuatro propiedades de los datos de Search Console causan la mayoría de las conclusiones erróneas. Las descripciones de las herramientas y la habilidad incluida los cubren en profundidad; brevemente:

1. Los datos tienen un retraso de ~3 días. Usa lastDays y las herramientas elegirán una ventana segura. Un rango que termina hoy muestra una caída falsa.

2. Los datos de consultas están filtrados por privacidad. Agrupar por query descarta silenciosamente las consultas raras, por lo que los clics a nivel de consulta nunca suman el total de la propiedad. Esa diferencia no es tráfico perdido.

3. La posición está invertida. La posición 3 supera a la posición 8; un cambio negativo es una mejora. compare_search_analytics devuelve un indicador improved explícito.

4. Los promedios se anulan. Las cifras planas de los titulares ocultan habitualmente grandes movimientos compensatorios. Agrupa por página o consulta antes de concluir que nada ha cambiado.

Cuotas

• Análisis de búsqueda: ~1.200 consultas/minuto por propiedad.

• Inspección de URL: ~2.000/día por propiedad — la restricción limitante. Muestrea deliberadamente.

No disponible a través de la API

El informe agregado de Cobertura de indexación, las pruebas de URL en vivo, la solicitud de indexación, Core Web Vitals, las acciones manuales, los problemas de seguridad, los informes de enlaces y las eliminaciones no tienen equivalente en la API, por lo que no están aquí. inspect_url por URL es el sustituto más cercano para las cuestiones de cobertura.

Habilidad del agente

skills/google-search-console/ es una habilidad lista para instalar que enseña a un agente a usar bien estas herramientas: los errores anteriores, una escalera de diagnóstico para cambios de tráfico, heurísticas para encontrar oportunidades y una tabla de consulta de estados de cobertura.

cp -r skills/google-search-console ~/.claude/skills/

El mismo material de referencia está disponible en tiempo de ejecución a través de los recursos gsc://guide/* del servidor, por lo que los agentes sin la habilidad instalada aún pueden leerlo.

Desarrollo

npm install
npm run build       # compile to dist/
npm run typecheck
npm test
npm run cf:dev      # Worker locally via wrangler

Comprobación manual rápida contra el transporte HTTP:

GSC_CREDENTIALS=<blob> npm run build && node dist/bin/cli.js http &

curl -s http://127.0.0.1:8787/mcp \
  -H 'content-type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}' | jq '.result.tools[].name'

Solución de problemas

Seguridad

• El blob de credenciales es tu acceso a Google. No lo hagas commit, no lo pegues en documentos compartidos. Revócalo en myaccount.google.com/permissions.

• El modo HTTP se vincula a 127.0.0.1 por defecto y valida Origin contra ALLOWED_ORIGINS para bloquear el reenlace de DNS. Sin configurar significa que no se permite ningún origen de navegador: enuméralos explícitamente, o usa * para optar por no participar en la comprobación. /health y / están exentos; no exponen ninguna capacidad con credenciales.

• La comparación del secreto compartido está verificada por longitud y es de tiempo constante.

• El despliegue predeterminado de Worker no almacena credenciales en absoluto.

• --read-only / GSC_READ_ONLY=1 bloquea la mutación del sitemap independientemente del alcance OAuth concedido.

Licencia

MIT