mcp-google-gsc

Servidor MCP para Google Search Console: análisis de búsqueda, inspección de URL y gestión de sitios a través de Claude.

Características

• Análisis de búsqueda -- Consulta clics, impresiones, CTR y posición con filtros de dimensión flexibles (consulta, página, dispositivo, país, fecha)

• Inspección de URL -- Comprueba el estado de indexación, la usabilidad móvil y los resultados enriquecidos de cualquier URL

• Listado de sitios -- Lista todas las propiedades de Search Console verificadas a las que puede acceder tu cuenta autenticada (usuario OAuth o cuenta de servicio)

• Soporte multi-cliente -- Gestiona múltiples propiedades de GSC con mapeo de configuración por directorio

Related MCP server: gsc-mcp-server

Instalación

Desde npm

npm install mcp-google-gsc

Desde el código fuente

git clone https://github.com/mharnett/mcp-search-console.git
cd mcp-google-gsc
npm install
npm run build

Configuración

Seguridad: Nunca compartas tu archivo .mcp.json ni lo confirmes en git: puede contener credenciales de API. Añade .mcp.json a tu .gitignore.

mcp-gsc admite dos modos de autenticación. Elige el que se adapte a tu configuración. Ninguno requiere que un archivo viva en una ruta local fija de la máquina: las credenciales provienen de variables de entorno (o de un config.json que crees).

Qué modo usar:

• Cuenta de servicio (Modo B) -- recomendado para uso desatendido / servidor / sin interfaz. Una cuenta de servicio no tiene inicio de sesión interactivo que expire o requiera nuevo consentimiento, por lo que es la opción adecuada para implementaciones siempre activas. El único requisito de configuración es que el correo electrónico de la cuenta de servicio debe tener acceso otorgado en cada propiedad de Search Console que quieras consultar (ver Modo B).

• OAuth de usuario (Modo A) -- para uso personal / interactivo, donde quieras autorizar con tu propio inicio de sesión de Google.

Precedencia cuando ambos están configurados: si se establece explícitamente un archivo de clave de cuenta de servicio (GOOGLE_APPLICATION_CREDENTIALS, o credentials_file en config.json), gana sobre cualquier token de actualización OAuth o credenciales OAuth almacenadas. Si no se configura ninguno, el servidor falla de forma ruidosa al inicio con un mensaje de incorporación en lugar de adivinar silenciosamente: no hay un valor predeterminado local de máquina ni una conmutación por error silenciosa en tiempo de ejecución entre modos.

Modo A: OAuth de usuario (trae tu propia cuenta de Google)

Usa esto si quieres autorizar con tu propio inicio de sesión de Google (la cuenta que tiene acceso a Search Console). Es mejor para uso personal / interactivo.

1. En Google Cloud Console, crea un ID de cliente OAuth 2.0 de tipo Aplicación de escritorio y habilita la API de Search Console. (Para un cliente de aplicación de escritorio, Google acepta cualquier redirección de bucle local http://localhost; no necesitas pre-registrar un puerto).

2. Exporta tus credenciales de cliente:

   export GOOGLE_GSC_CLIENT_ID=...apps.googleusercontent.com
   export GOOGLE_GSC_CLIENT_SECRET=...

3. Genera un token de actualización (abre tu navegador, usa PKCE + access_type=offline):

   node get-refresh-token.cjs

   No redirijas la salida estándar de este comando a un registro compartido: imprime el token de actualización en la salida estándar por diseño.

4. Copia la línea impresa en tu entorno:

   export GOOGLE_GSC_REFRESH_TOKEN=...

El servidor lee GOOGLE_GSC_CLIENT_ID, GOOGLE_GSC_CLIENT_SECRET y GOOGLE_GSC_REFRESH_TOKEN del entorno en tiempo de ejecución.

Alternativamente, ejecuta el asistente guiado npx mcp-gsc-auth, que realiza el mismo flujo OAuth PKCE, te permite elegir una propiedad de Search Console predeterminada y escribe el resultado en un archivo de credenciales por usuario.

Modo B: Cuenta de servicio (recomendado para uso desatendido / servidor)

Usa esto para contextos de servidor / sin interfaz / siempre activos: es la ruta recomendada cuando no hay un humano presente para completar o actualizar un inicio de sesión interactivo.

1. Crea una cuenta de servicio de Google Cloud con acceso a la API de Search Console y descarga su archivo de clave JSON.

2. Otorga acceso al correo electrónico de la cuenta de servicio en cada propiedad de Search Console que quieras consultar (agrégala como usuario en Search Console). Sin esta concesión en la propiedad, la cuenta de servicio puede autenticarse pero no verá ningún sitio.

3. Apunta el servidor al archivo de clave a través de una variable de entorno (sin ruta fija):

   export GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/service-account-key.json

Alcance de OAuth

Ambos modos solicitan un único alcance de solo lectura: https://www.googleapis.com/auth/webmasters.readonly. Las cuatro herramientas son de lectura; nada escribe, por lo que el servidor nunca solicita acceso de lectura/escritura.

El alcance se define una vez en config.json bajo oauth.scope (ver config.example.json). El asistente OAuth y el tiempo de ejecución leen el mismo valor, por lo que nunca divergen. Si config.json está ausente (por ejemplo, una instalación nueva), se usa el valor predeterminado de solo lectura confirmado.

Configuración multi-cliente (opcional)

Para mapear directorios de trabajo a propiedades de Search Console, crea un config.json en la raíz del proyecto (ver config.example.json):

{
  "oauth": {
    "scope": "https://www.googleapis.com/auth/webmasters.readonly"
  },
  "clients": {
    "my-project": {
      "name": "My Project",
      "folder": "/path/to/project",
      "site_url": "https://example.com/"
    }
  }
}

Uso

Añade a tu .mcp.json de Claude Code:

{
  "mcpServers": {
    "gsc": {
      "command": "node",
      "args": ["/path/to/mcp-gsc/dist/index.js"]
    }
  }
}

O si está instalado globalmente:

{
  "mcpServers": {
    "gsc": {
      "command": "npx",
      "args": ["mcp-google-gsc"]
    }
  }
}

Claude Desktop: Añade a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows).

Herramientas

gsc_search_analytics

Admite dimensiones: query, page, device, country, date. Filtra por cualquier dimensión con operadores como equals, contains, notContains. El rango de fechas predeterminado son los últimos 28 días.

gsc_inspection

Devuelve la cobertura de indexación, el estado de rastreo, el veredicto de usabilidad móvil y los detalles de resultados enriquecidos para una URL específica dentro de una propiedad.

Arquitectura

• Resiliencia -- Usa cockatiel para reintentos con retroceso exponencial y patrones de interruptor de circuito en todas las llamadas a la API de Google

• Registro -- Registro estructurado mediante pino con niveles de registro configurables

• Manejo de respuestas -- Las respuestas se truncan a 200KB para mantenerse dentro de los límites de transporte de MCP

Licencia

MIT -- ver LICENSE.

Construido por Mark Harnett / drak-marketing