Cómo Conectar Google Search Console a Claude Code con MCP-GSC

mcp-gsc es un servidor MCP (Model Context Protocol) open source que conecta Google Search Console con Claude Desktop, Cursor, Claude Code y cualquier cliente compatible con MCP. Una vez configurado, puedes analizar tu SEO usando lenguaje natural sin abrir el panel de GSC.

📦 Repositorio oficial: github.com/AminForou/mcp-gsc | Versión actual: 0.3.2 (abril 2026) | Licencia: MIT

1. ¿Qué es mcp-gsc? — Las 20 tools disponibles

mcp-gsc expone 20 herramientas que puedes invocar directamente desde Claude con lenguaje natural:

Tool / Comando	Qué hace
get_capabilities	Lista todas las tools y muestra el estado de autenticación
list_properties	Muestra todas tus propiedades de GSC
get_site_details	Detalles de una propiedad específica
get_search_analytics	Top queries y páginas con clics, impresiones, CTR y posición
get_performance_overview	Resumen de rendimiento del sitio
compare_search_periods	Compara rendimiento entre dos períodos
get_search_by_page_query	Términos de búsqueda que llevan tráfico a una página
get_advanced_search_analytics	Analytics con filtros por país, dispositivo, query, página
inspect_url_enhanced	Estado detallado de crawl/indexación de una URL
batch_url_inspection	Inspecciona hasta 10 URLs a la vez
check_indexing_issues	Detecta problemas de indexación en múltiples URLs
get_sitemaps	Lista todos los sitemaps
list_sitemaps_enhanced	Info detallada de sitemaps incluyendo errores
manage_sitemaps	Enviar o eliminar sitemaps
get_sitemap_details	Detalles completos de un sitemap específico
submit_sitemap	Enviar un nuevo sitemap a Google
delete_sitemap	Eliminar un sitemap enviado
add_site	Agregar una nueva propiedad a GSC
delete_site	Eliminar una propiedad de GSC
reauthenticate	Vuelve a hacer el login OAuth (cambiar cuenta)

2. Requisitos previos

• ✅ Claude Desktop instalado — descarga en claude.ai/download
• ✅ Python 3.11+ instalado en tu sistema
• ✅ Cuenta de Google con acceso a Google Search Console
• ✅ Al menos una propiedad verificada en GSC
• ✅ Acceso a Google Cloud Console para crear credenciales (gratuito)

⚠️ Importante: Este MCP corre localmente en tu máquina. Requiere la app de escritorio de Claude Desktop, NO funciona en la versión web de claude.ai en el navegador.

3. Crear credenciales en Google Cloud

Antes de instalar el servidor, necesitas un archivo JSON con credenciales de Google. Tienes dos opciones:

Opción A: OAuth (Recomendada para uso personal)

Usa tu propia cuenta de Google. Al primer uso, abre el navegador para iniciar sesión y guarda el token automáticamente. Solo se pide el login una vez.

1. Ve a console.cloud.google.com y crea o selecciona un proyecto
2. Busca “Search Console API” en la Biblioteca de APIs y habilítala
3. Ve a Credenciales → Crear credenciales → ID de cliente OAuth
4. Configura la pantalla de consentimiento OAuth (puedes dejarlo en modo externo/pruebas)
5. En “Tipo de aplicación” selecciona Aplicación de escritorio y haz clic en Crear
6. Descarga el archivo JSON generado y guárdalo en una ruta permanente

📁 Ruta recomendada: ~/Documents/gsc_client_secrets.json

💡 Tip: Guarda el archivo JSON en una ubicación que no vayas a mover ni borrar. La ruta que uses aquí la necesitarás en el paso de configuración.

Opción B: Service Account (Para automatización o equipos)

Útil cuando necesitas acceso sin interacción del usuario. Requiere agregar el email del service account como usuario en cada propiedad de GSC.

1. Ve a console.cloud.google.com y habilita la Search Console API (igual que Opción A)
2. Ve a Credenciales → Crear credenciales → Cuenta de servicio
3. Llena el formulario y haz clic en Crear y continuar
4. En la sección Claves → Agregar clave → Crear clave nueva → JSON → Descargar
5. Guarda el JSON en una ruta permanente (ej: ~/Documents/gsc_service_account.json)
6. En GSC: Configuración → Usuarios y permisos → Agregar usuario → pega el email del service account → Acceso completo

4. Instalación del servidor MCP

Hay dos métodos. El Método A (uvx) es el recomendado: sin clonar repositorios, sin entornos virtuales, se actualiza automático.

Método A: uvx (Recomendado)

uvx descarga y ejecuta el servidor automáticamente. Solo necesitas instalar uv una vez y apuntar a él desde la config.

Mac / Linux — instalar uv:

Ejecuta los tres comandos en orden en la Terminal:

# 1. Descargar e instalar
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Activar en la sesión actual de Terminal
source $HOME/.local/bin/env

# 3. Hacerlo permanente para futuras sesiones
echo 'source $HOME/.local/bin/env' >> ~/.zshrc

Obtener la ruta completa de uvx:

which uvx
# Resultado típico en Mac: /Users/TU_USUARIO/.local/bin/uvx

Windows — instalar uv:

Ejecuta en PowerShell (como administrador):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Luego obtén la ruta de uvx:

where.exe uvx
# Resultado típico: C:\Users\JimmyPro\.local\bin\uvx.exe

Verificar instalación:

uv --version

⚠️ Solución rápida: Si ves “command not found” después de instalar, ejecuta: source $HOME/.local/bin/env (Mac/Linux) o reinicia PowerShell (Windows).

Método B: Clonar el repositorio (Avanzado)

Usa este método solo si quieres modificar el código fuente.

git clone https://github.com/AminForou/mcp-gsc.git
cd mcp-gsc
uv venv .venv
uv pip install -r requirements.txt

5. Configurar Claude Desktop

Edita el archivo de configuración de Claude Desktop agregando el bloque del servidor. Localiza el archivo según tu sistema operativo:

Sistema Operativo	Ruta del archivo de configuración
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

Configuración con OAuth (Mac/Linux) — Método uvx

Reemplaza /FULL/PATH/TO/uvx con el resultado de which uvx y ajusta la ruta del JSON:

{
  "mcpServers": {
    "gscServer": {
      "command": "/Users/tu_usuario/.local/bin/uvx",
      "args": ["mcp-search-console"],
      "env": {
        "GSC_OAUTH_CLIENT_SECRETS_FILE": "/Users/tu_usuario/Documents/gsc_client_secrets.json"
      }
    }
  }
}

Configuración con OAuth (Windows) — Método uvx

{
  "mcpServers": {
    "gscServer": {
      "command": "C:\\Users\\JimmyPro\\.local\\bin\\uvx.exe",
      "args": ["mcp-search-console"],
      "env": {
        "GSC_OAUTH_CLIENT_SECRETS_FILE": "C:\\Users\\JimmyPro\\Documents\\gsc_client_secrets.json"
      }
    }
  }
}

Configuración con Service Account — Método uvx

{
  "mcpServers": {
    "gscServer": {
      "command": "/FULL/PATH/TO/uvx",
      "args": ["mcp-search-console"],
      "env": {
        "GSC_CREDENTIALS_PATH": "/full/path/to/service_account.json",
        "GSC_SKIP_OAUTH": "true"
      }
    }
  }
}

Configuración con repositorio clonado (Método B)

{
  "mcpServers": {
    "gscServer": {
      "command": "/full/path/to/mcp-gsc/.venv/bin/python",
      "args": ["/full/path/to/mcp-gsc/gsc_server.py"],
      "env": {
        "GSC_OAUTH_CLIENT_SECRETS_FILE": "/full/path/to/gsc_client_secrets.json"
      }
    }
  }
}

⚠️ Crítico: Siempre usa rutas absolutas. Nunca uses rutas relativas como ./credentials.json. Después de guardar el archivo de config, haz Cmd+Q (Mac) o cierra completamente Claude Desktop y vuelve a abrirlo.

6. Primer uso y verificación

Al abrir Claude Desktop por primera vez después de configurar el servidor:

• Si usas OAuth: se abrirá una ventana del navegador para iniciar sesión con tu cuenta de Google. Autoriza el acceso.
• Después del login, el token se guarda automáticamente. No te volverá a pedir login.

En Claude Desktop, inicia una nueva conversación y escribe:

👤 “Lista mis propiedades de GSC”

Si ves tu lista de propiedades, la conexión funciona correctamente. Para verificar el estado de auth y ver todas las tools disponibles:

👤 “Llama a get_capabilities”

💡 Tip: Si hay algún error de autenticación, Claude te indicará exactamente qué hacer. También puedes pedir: “llama a reauthenticate” para volver a hacer el login OAuth.

7. Variables de entorno

Puedes personalizar el comportamiento del servidor con estas variables en la sección env del config:

Variable	Default	Descripción
GSC_OAUTH_CLIENT_SECRETS_FILE	—	Ruta al JSON de credenciales OAuth (requerido con uvx OAuth)
GSC_CREDENTIALS_PATH	—	Ruta al JSON del Service Account
GSC_SKIP_OAUTH	false	Ponlo en "true" para forzar Service Account y saltar OAuth
GSC_DATA_STATE	all	"all" = igual al dashboard GSC. "final" = solo datos confirmados (2-3 días de retraso)
GSC_ALLOW_DESTRUCTIVE	false	Ponlo en "true" para habilitar add_site, delete_site y delete_sitemap

8. Ejemplos de uso — Prompts listos para usar

Análisis de rendimiento general

👤 "¿Cuál es el rendimiento de mi sitio mysite.com en los últimos 30 días?"

👤 "Muestra las top 20 queries de mysite.com con CTR menor al 2% y sugiere mejoras al title"

👤 "Crea un resumen visual de rendimiento de mysite.com para los últimos 28 días"

Comparación de períodos

👤 "Compara el rendimiento de mysite.com entre enero y febrero. ¿Qué queries mejoraron más?"

👤 "¿Ha habido caídas de tráfico importantes en las últimas semanas?"

Páginas específicas

👤 "¿Qué términos de búsqueda llevan tráfico a mysite.com/servicios?"

👤 "Analiza queries con altas impresiones pero posición mayor a 10, filtrado a móvil en México"

Indexación y sitemaps

👤 "Revisa si hay problemas de indexación en: mysite.com/about, mysite.com/contact, mysite.com/blog"

👤 "Inspecciona la URL mysite.com/landing y dame recomendaciones de acción"

👤 "¿Están mis sitemaps enviados y procesados correctamente?"

Skills predefinidos para Cursor

👤 "Run the SEO weekly report for mysite.com"

👤 "Check for keyword cannibalization on mysite.com"

👤 "Audit indexing for my top pages"

👤 "Find content opportunities for mysite.com"

9. Troubleshooting — Los 5 errores más comunes

❌ Error: spawn uvx ENOENT / command not found: uvx

Causa: Claude Desktop no encuentra uvx porque no tiene la ruta completa.

Solución: Usa la ruta absoluta en el config. Ejecuta which uvx (Mac) o where.exe uvx (Windows) y copia el resultado completo:

"command": "/Users/tu_usuario/.local/bin/uvx"   ← ruta completa, no solo "uvx"

❌ Error: uv --version: command not found después de instalar

Causa: La sesión actual de Terminal no conoce la ruta nueva.

Solución:

source $HOME/.local/bin/env   # Mac/Linux

# Agregar permanentemente:
echo 'source $HOME/.local/bin/env' >> ~/.zshrc

❌ Error: Authentication failed / credentials file not found

Causa: Ruta relativa o incorrecta al archivo de credenciales.

Solución: Usa siempre la ruta absoluta completa:

/Users/tu_usuario/Documents/client_secrets.json    ✅  (absoluta)
~/Documents/client_secrets.json                    ✅  (con ~)
client_secrets.json                                ❌  (relativa — NO funciona)

❌ MCP solo funciona en Claude Desktop, no en claude.ai web

Causa: Este servidor corre localmente. Solo funciona con la app de escritorio.

Solución: Descarga Claude Desktop en claude.ai/download

❌ El servidor aparece pero no muestra mis propiedades

Causa: Problema de autenticación o token expirado.

Solución: Escribe en Claude: "Llama a get_capabilities" para ver el estado de auth. Si hay error, escribe "llama a reauthenticate" para volver a iniciar sesión.

10. Configuración para Claude Code CLI

Si usas Claude Code en terminal en lugar de Claude Desktop, agrega el servidor en tu archivo de configuración MCP:

Archivo de configuración (Windows)

C:\Users\JimmyPro\.claude.json

Bloque a agregar dentro de mcpServers

"gscServer": {
  "command": "C:\\Users\\JimmyPro\\.local\\bin\\uvx.exe",
  "args": ["mcp-search-console"],
  "env": {
    "GSC_OAUTH_CLIENT_SECRETS_FILE": "C:\\Users\\JimmyPro\\Documents\\gsc_client_secrets.json"
  }
}

💡 Verificación: En Claude Code puedes verificar que el servidor esté activo ejecutando el comando /mcp en el CLI. Debería aparecer gscServer con estado connected.

---

Guías relacionadas

Si estás montando tu stack de SEO y automatización con Claude Code, estas guías complementan esta integración:

• Cómo instalar Claude SEO en Claude Code — auditorías SEO técnicas y de contenido que se apoyan en los datos de Search Console.
• Integrar Microsoft Clarity con Claude AI vía MCP — suma la capa de comportamiento (CRO) al análisis de búsqueda.
• Instalar Royal MCP: WordPress + Claude Code — aplica en tu WordPress las mejoras que detectes en GSC.

Documentado por webmarketingmx.pro • Basado en github.com/AminForou/mcp-gsc • MIT License