gsc-ga4-mcp

Un pequeño servidor MCP local que ofrece a Claude Code acceso de solo lectura a Google Search Console y GA4, además de unas cuantas herramientas que cruzan los dos conjuntos de datos.

El problema

El trabajo de SEO en un asistente de IA suele significar exportar CSV desde Search Console, exportar más CSV desde GA4, pegar ambos en un chat y repetir todo cada vez que necesitas una cifra actualizada. Los dos conjuntos de datos tampoco encajan nunca por sí solos: Search Console registra impresiones, clics y CTR; GA4 registra sesiones, interacción y conversiones. Responder «qué páginas reciben tráfico pero lo desperdician» implica cruzarlas a mano por URL.

Google publica un servidor MCP oficial para Analytics, pero no cubre Search Console. Existen servidores comunitarios para Search Console, pero si los datos pertenecen a clientes, ejecutar un envoltorio pequeño que puedas leer de principio a fin es mejor que confiar en el de otro.

Este servidor llama directamente a las APIs oficiales de Google, con permisos de solo lectura, desde tu propia máquina.

Related MCP server: Google Search Console MCP Server

Qué hace

Veinte herramientas MCP a través de stdio.

Search Console

GA4

Análisis combinado

Config

project_mappings y project_lookup leen un archivo local que asigna un nombre de proyecto o cliente a su propiedad de GSC y su propiedad de GA4, de modo que puedas decir «cruza GSC y GA4 para example.com» en lugar de recordar properties/123456789.

Stack

Node.js + TypeScript. @modelcontextprotocol/sdk para el servidor, google-auth-library para la autenticación y zod para los esquemas de herramientas. Sin base de datos, sin backend alojado y sin telemetría: el proceso se ejecuta localmente y Claude Code lo inicia con stdio.

Los alcances son de solo lectura y esa es toda la superficie de permisos:

• https://www.googleapis.com/auth/webmasters.readonly

• https://www.googleapis.com/auth/analytics.readonly

Las credenciales quedan fuera del repositorio; por defecto en ~/.config/gsc-ga4-mcp/.

Instalación

1. Instalar

git clone https://github.com/YOUR_USER/gsc-ga4-mcp.git
cd gsc-ga4-mcp
npm install
npm run build
mkdir -p ~/.config/gsc-ga4-mcp

2. Habilitar las APIs

En Google Cloud Console, crea o elige un proyecto y habilita estas:

• Google Search Console API

• Google Analytics Data API

• Google Analytics Admin API

3. Crear credenciales de OAuth

En APIs y servicios → Pantalla de consentimiento de OAuth, configure la pantalla de consentimiento. Elige la opción Externa si las propiedades que gestionas no están todas en un mismo Google Workspace y agrega tu correo como usuario de prueba mientras la aplicación esté en modo de pruebas.

En APIs y servicios → Cuentas y servicios → Credenciales, crea un cliente de OAuth de tipo App de escritorio, descarga el JSON y guarda el archivo como ~/.config/gsc-ga4-mcp/oauth-client.json.

Para el trabajo con clientes, si prefieres aislar permisos por cuenta, usa una cuenta de servicio y añade su correo a cada propiedad de GSC GA4 con acceso de lectura. Establece la variable GOOGLE_AUTH_MODE=service_account y haz que GOOGLE_SERVICE_ACCOUNT_KEY_FILE apunte al fichero de clave.

4. Configurar

cp .env.example .env
cp projects.example.json ~/.config/gsc-ga4-mcp/projects.json

Las rutas de .env deben ser absolutas; ~ no se expande.

GOOGLE_AUTH_MODE=oauth
GOOGLE_OAUTH_CREDENTIALS_FILE=/Users/YOUR_USER/.config/gsc-ga4-mcp/oauth-client.json
GOOGLE_TOKEN_PATH=/Users/YOUR_USER/.config/gsc-ga4-mcp/token.json
GOOGLE_OAUTH_REDIRECT_URI=http://127.0.0.1:3000/oauth2callback
PROJECTS_CONFIG=/Users/YOUR_USER/.config/gsc-ga4-mcp/projects.json
MCP_DEFAULT_GSC_SITE=sc-domain:example.com
MCP_DEFAULT_GA4_PROPERTY=properties/123456789
MAX_ROWS=25000

Diagrama de projectos (projects.json):

{
  "projects": [
    {
      "name": "My Site",
      "client": "Internal",
      "domain": "example.com",
      "gscSiteUrl": "sc-domain:example.com",
      "ga4Property": "properties/123456789",
      "notes": "Replace with the real GA4 property ID."
    }
  ]
}

5. Autorizar

npm run auth

El script inicia un listener de loopback en 127.0.0.1:3000 y imprime una URL de Google. Ábrela, aprueba los permisos de solo lectura y el token quedará escrito en GOOGLE_TOKEN_PATH.

6. Registrar en Claude Code

claude mcp add google-seo -- node /ABSOLUTE/PATH/TO/gsc-ga4-mcp/dist/index.js
claude mcp list

O incorpora un .mcp.json al proyecto donde quieras usar las herramientas (consulta .mcp.example.json):

{
  "mcpServers": {
    "google-seo": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/gsc-ga4-mcp/dist/index.js"],
      "env": {
        "GOOGLE_AUTH_MODE": "oauth",
        "GOOGLE_OAUTH_CREDENTIALS_FILE": "/Users/YOUR_USER/.config/gsc-ga4-mcp/oauth-client.json",
        "GOOGLE_TOKEN_PATH": "/Users/YOUR_USER/.config/gsc-ga4-mcp/token.json",
        "PROJECTS_CONFIG": "/Users/YOUR_USER/.config/gsc-ga4-mcp/projects.json",
        "MCP_DEFAULT_GSC_SITE": "sc-domain:example.com",
        "MCP_DEFAULT_GA4_PROPERTY": "properties/123456789"
      }
    }
  }
}

Usa el registro por CLI si prefieres que rutas y valores por defecto de propiedades no se mantengan fuera del repositorio.

Uso con Claude Code

Solicítalo en lenguaje natural; Claude elegirá las herramientas.

Use gsc_list_sites and ga4_list_properties. Give me a table of the GSC sites
and GA4 properties I can reach.

Analyse organic traffic for sc-domain:example.com over the last 90 days using
gsc_top_queries and gsc_top_pages.

Cross GSC and GA4 for example.com over the last 90 days. Find pages with high
impressions and low CTR, and rank the opportunities by likely impact.

Run seo_opportunity_report and group the output into quick wins, pages that
need a rewrite, and pages that miss search intent.

Inspect https://www.example.com/page/ with gsc_url_inspection and tell me
whether Google has it indexed.

Notas de uso

• Mantén .env, token.json, projects.json y cualquier clave de cuenta de servicio fuera del control de versiones. El .gitignore que se incluye ya los cubre.

• Los datos analíticos de los clientes son confidenciales. No pegues salidas completas en herramientas que el cliente no haya aprobado.

• Revoca el token o la cuenta de servicio cuando un contrato termine.

• MAX_ROWS limita el tamaño de las respuestas. Reduce el valor si te contestan demasiado datos.

Solución de problemas

• Claude Code no ve las herramientas. Ejecuta claude Es mcp list y, luego, /mcp dentro de Claude Code.

• Errores de token de OAuth. Vuelve a ejecutar npm run auth y confirma que GOOGLE_TOKEN_PATH es directo.

• access_denied. Añade tu correo como usuario de prueba en la pantalla de consentimiento de OAuth mientras la aplicación esté en testing.

• Un dominio no aparece en GSC. Las credenciales deben tener acceso a esa propiedad exacta: sc-domain:example.com y https://www.example.com/ son propiedades distintas.

• Falta un propiedad de GA4. El usuario o la cuenta de servicio necesita al menos permiso de consulta (Viewer) en el nivel de propiedad.

• Error en gsc_url_inspection . inspectionUrl debe estar dentro del siteUrl y las propiedades de prefijo de URL deben terminar en /.

• Métricas de GA4 no válidas. Usa los nombres de dimensiones y métricas oficiales de GA4; runReport rechaza cualquier otro.

Referencias

• Documentación de Claude Code MCP

• Protocolo de Contexto del Modelo

• Search Console API

• GA4 Data API

• Google Analytics Admin API

• Google OAuth scopes

Licencia

MIT. Ver el archivo LICENSE.