gsc-ga4-mcp
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: SCMCP
Qué hace
Veinte herramientas MCP a través de stdio.
Search Console
Herramienta | Propósito |
| Sitios visibles para las credenciales actuales |
| Ejecuta |
| Principales consultas para un rango de fechas |
| Principales páginas para un rango de fechas |
| Desglose de consulta × página |
| Estado de indexación de una URL concreta |
GA4
Herramienta | Propósito |
| Resúmenes de cuentas y propiedades |
| Ejecuta |
| Páginas por sesiones/vistas |
| Sesiones por fuente/medio |
| Páginas de aterrizaje con métricas de interacción |
| Recuento de eventos |
| Los últimos 30 minutos de actividad |
Análisis combinado
Herramienta | Propósito |
| En una gal invierte ambos e informes, se agrupa en victorías rápidas y reesesperanzas; |
| Cruza las páginas de GSC con las de GA4 por ruta de URL |
| Posicionan bien, pero sin conseguir el clic |
| Consiguen el clic, pero pierden al visitante |
| Páginas cuyo rendimiento ha decaído |
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.readonlyhttps://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-mcp2. 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.jsonLas 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=25000Diagrama 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 authEl 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 listO 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.jsony cualquier clave de cuenta de servicio fuera del control de versiones. El.gitignoreque 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_ROWSlimita 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 listy, luego,/mcpdentro de Claude Code.Errores de token de OAuth. Vuelve a ejecutar
npm run authy confirma queGOOGLE_TOKEN_PATHes 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.comyhttps://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.inspectionUrldebe estar dentro delsiteUrly 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;
runReportrechaza cualquier otro.
Referencias
Licencia
MIT. Ver el archivo LICENSE.
Available Tools
20 toolscompare_gsc_ga4_pagesC
Join GSC page performance with GA4 landing-page engagement.
Inputs: endDate (required), startDate (required), siteUrl, property, +1 more.
content_refresh_candidatesC
Rank pages that may deserve a content refresh based on GSC opportunity and GA4 engagement.
Inputs: endDate (required), startDate (required), siteUrl, property, +1 more.
find_high_impression_low_ctr_pagesC
Find GSC pages with high impressions and low CTR.
Inputs: endDate (required), startDate (required), maxCtr, siteUrl, +2 more.
find_pages_with_clicks_but_low_engagementC
Find pages with GSC clicks but weak GA4 engagement.
Inputs: endDate (required), startDate (required), siteUrl, property, +3 more.
ga4_eventsC
GA4 events by event name.
Inputs: endDate (required), startDate (required), limit, property.
ga4_landing_pagesD
GA4 landing pages with engagement metrics.
Inputs: endDate (required), startDate (required), limit, property.
ga4_list_propertiesA
List GA4 accounts and property summaries visible to the credentials.
Inputs: no named parameters.
ga4_realtimeD
GA4 realtime active users report.
Inputs: limit, metrics, property, dimensions.
ga4_run_reportC
Run a raw GA4 Data API report.
Inputs: endDate (required), metrics (required), startDate (required), dimensions (required), +3 more.
ga4_top_pagesC
Top GA4 pages by views, users, and sessions.
Inputs: endDate (required), startDate (required), limit, property.
ga4_traffic_sourcesB
GA4 traffic sources by default channel group and source/medium.
Inputs: endDate (required), startDate (required), limit, property.
gsc_list_sitesA
List Google Search Console sites visible to the current credentials.
Inputs: no named parameters.
gsc_query_page_matrixC
GSC query/page matrix for finding page-level keyword opportunities.
Inputs: endDate (required), startDate (required), siteUrl, rowLimit.
gsc_search_analyticsD
Run a raw Search Console Search Analytics query.
Inputs: endDate (required), startDate (required), type, siteUrl, +3 more.
gsc_top_pagesC
Top GSC pages by clicks/impressions.
Inputs: endDate (required), startDate (required), siteUrl, rowLimit.
gsc_top_queriesC
Top GSC queries by clicks/impressions.
Inputs: endDate (required), startDate (required), siteUrl, rowLimit.
gsc_url_inspectionA
Inspect Google index status for a URL under a GSC property.
Inputs: inspectionUrl (required), siteUrl, languageCode.
project_lookupB
Find a local project mapping by project name, client, or domain.
Inputs: nameOrDomain (required).
project_mappingsB
List local domain/client mappings from PROJECTS_CONFIG.
Inputs: no named parameters.
seo_opportunity_reportC
Compact SEO opportunity report combining high-impression/low-CTR and low-engagement candidates.
Inputs: endDate (required), startDate (required), siteUrl, property, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Several tools overlap heavily: gsc_search_analytics is a raw query tool but gsc_top_queries, gsc_top_pages, and gsc_query_page_matrix are just specialized versions of it. Similarly, ga4_run_report overlaps with ga4_top_pages, ga4_traffic_sources, ga4_landing_pages, and ga4_events, while the final four SEO opportunity tools substantially duplicate one another in purpose.
Naming is mostly consistent with service prefixes (gsc_, ga4_) followed by descriptive topic or verb_noun forms like list_sites and run_report. Minor inconsistencies exist, such as project_mappings/project_lookup using a different pattern and the verb-less gsc_search_analytics, but overall the convention is predictable.
20 tools is on the heavier side, but the server intentionally covers two analytics platforms plus cross-platform analysis, so the count is defensible. A few of the derived report tools are redundant enough that the set could be trimmed, but it does not feel bloated beyond reason.
The toolset covers the core read-only SEO workflow well: GSC site listing, raw and curated search analytics, URL inspection, GA4 property/report access, and cross-platform opportunity analysis. Minor gaps exist, such as no GSC sitemap or index-request tools and no GA4 audience or funnel reports, but the raw query tools provide a workaround.
Maintenance
Related MCP Connectors
Read-only Google Ads, GA4 and Search Console data for Claude, with no Google Cloud setup.
SEO research, Search Console, GA4 and PPC tools for Claude and ChatGPT.
Google Search Console, GA4, Bing Webmaster and PageSpeed MCP for Claude, ChatGPT, Cursor. Free.
GA4, Google Ads and Search Console in Claude. Read-only OAuth, multi-account for agencies.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables Claude to access Google Search Console data including search performance, URL indexation, sitemaps, and built-in SEO analysis tools such as trending queries, cannibalization detection, and traffic drop diagnostics.10-
- FlicenseNot gradedqualityDmaintenanceEnables users to securely connect Claude to their own Google Search Console data, providing custom SEO analyses such as quick wins, content decay, and cannibalization, plus optional BigQuery bulk export, with per-user token scoping and read-only tools.-
- FlicenseNot gradedqualityNot gradedmaintenanceEnables users to query Google Search Console data interactively from Claude Desktop and via CLI, providing search analytics, period comparisons, branded split, indexing status, sitemaps, and full CSV exports.-
- AlicenseBqualityBmaintenanceEnables Claude Desktop to analyze Google Search Console performance, diagnose traffic drops and indexing issues, and run technical SEO checks such as robots.txt, redirects, HTTPS, DNS, Core Web Vitals, and crawl stats using read-only Google APIs and local server logs.44MIT