search-console-mcp

Servidor MCP para Google Search Console que expone la Search Console API oficial como herramientas para agentes de IA.

Su enfoque es el rendimiento de búsqueda y la salud del índice: consultar clics, impresiones, CTR y posición por consulta, página, país, dispositivo o fecha; comprobar si una URL está indexada y por qué no, y gestionar los sitemaps y las propiedades de una cuenta.

Lo que deliberadamente no hace: no solicita la (re)indexación de URLs — la Indexing API independiente solo admite páginas de ofertas de empleo y emisiones en directo —, no verifica la propiedad de un sitio (un propietario debe añadir la cuenta de servicio a cada propiedad) y no accede a datos de Google Analytics (para eso sirve la Analytics Data API, que no está relacionada).

Los borrados son opt-in. delete_sitemap y delete_site solo se registran cuando GOOGLE_SEARCH_CONSOLE_ALLOW_DESTRUCTIVE está establecida; ver Configuración.

Instalación

claude mcp add search-console \
  -e GOOGLE_SERVICE_ACCOUNT_KEY_PATH=/path/to/service-account.json \
  -e GOOGLE_SEARCH_CONSOLE_SITE_URL=https://example.com/ \
  -- npx -y @orellbuehler/search-console-mcp

Los parámetros -e deben aparecer antes del separador --; todo lo que vaya después de -- se pasa al proceso del servidor en lugar de leerse como configuración.

Obtención de una clave de cuenta de servicio

1. En la consola de Google Cloud, selecciona o crea un proyecto y habilita la Google Search Console API.

2. Ve a IAM y administración → Cuentas de servicio → Crear cuenta de servicio. Puedes omitir los pasos opcionales de "conceder acceso"; los permisos de Search Console se conceden por separado, no mediante roles de IAM de Cloud.

3. Abre la nueva cuenta de servicio, ve a la pestaña Claves y elige Añadir clave → Crear clave nueva → JSON. El archivo se descarga una sola vez y no se puede volver a recuperar.

4. En Search Console, abre la propiedad, ve a Configuración → Usuarios y permisos → Añadir usuario y pega la dirección de correo de la cuenta de servicio (name@project-id.iam.gserviceaccount.com). Concede:

   • Restringido o Completo para las herramientas de lectura (analytics, sitemaps, inspección de URLs)

   • Completo para submit_sitemap y delete_sitemap

5. Repite el paso 4 con cada propiedad que el servidor deba ver: una cuenta de servicio no puede verificar propiedades por sí misma.

6. Haz que GOOGLE_SERVICE_ACCOUNT_KEY_PATH apunte al archivo JSON descargado.

Trata la clave JSON como una contraseña: conlleva todos los permisos que hayas concedido y no tiene un segundo factor delante. Mantenla fuera del repositorio y plantéate aplicar chmod 600.

Configuración

Una propiedad se identifica bien como propiedad de prefijo de URL como https://example.com/ (el protocolo y la barra final cuentan; https://example.com/ y http://example.com/ son propiedades distintas), bien como propiedad de dominio como sc-domain:example.com, que cubre todos los subdominios y protocolos. Usa la forma concreta con la que la propiedad se añadió a Search Console; list_sites muestra las cadenas exactas.

Uso con Claude Code

{
  "mcpServers": {
    "search-console": {
      "command": "npx",
      "args": ["-y", "@orellbuehler/search-console-mcp"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY_PATH": "/path/to/service-account.json",
        "GOOGLE_SEARCH_CONSOLE_SITE_URL": "https://example.com/"
      }
    }
  }
}

Ejemplos de prompts

• "¿Cuáles son mis consultas de búsqueda principales de este mes?"

• "¿Qué páginas reciben más clics de Google y cómo ha cambiado eso respecto a los últimos 28 días?"

• "Mostrar consultas que contengan 'pricing' en las que aparezcamos por debajo de la posición 10: candidatas claras."

• "¿Cuánto de nuestro tráfico es móvil frente a escritorio?"

• "Representar gráficamente nuestros clics e impresiones diarios de los últimos tres meses."

• "¿Qué países obtienen impresiones de nosotros pero casi ningún clic?"

• "¿Está indexada https://example.com/blog/launch? Si no, ¿por qué?"

• "Lista nuestros sitemaps y dime si alguno tiene errores o avisos."

• "Vuelve a enviar el sitemap después de la restructuración de ayer."

• "¿Qué páginas posicionadas para 'mcp server' compiten entre sí?"

• "Compara nuestro tráfico de Discover con el de búsqueda web de este trimestre."

Herramientas

Analítica de búsqueda

Sitemaps

Sitios

Inspección de URLs

Notas y avisos

• Los datos de rendimiento tienen un desfase de unos 2–3 días. Las herramientas de conveniencia ajustan por defecto su rango de fechas a 3 días antes; data_state: "all" incluye datos recientes pero posiblemente incompletos.

• Retención de 16 meses. Las consultas anteriores a ese rango no devuelven filas.

• Filtrado por privacidad. Las filas de consultas poco frecuentes se omiten, por lo que sumar las filas por consulta da un total menor que el real; se debe consultar sin dimensiones para obtener totales exactos.

• 25 000 filas por llamada. Hay que paginar con start_row; una respuesta con menos filas que limit es la última página.

• La cuota de inspección de URLs es de unas 2 000 llamadas al día por propiedad y 600 por minuto: inspecciona de forma selectiva, no masiva.

• La dimensión hour requiere data_state: "hourly_all" y solo cubre los últimos 10 días sbaya.

• **Tus datos de búsqueda llegan al LLM.**Todo lo que devuelve una herramienta se convierte en el contexto del modelo; no conectes propiedades cuyos datos no deban salir de tu entorno.

Desarrollo

npm install
npm run build         # tsc -p tsconfig.build.json -> dist/
npm test              # vitest run
npm run lint          # eslint src
npm run typecheck     # tsc --noEmit
npm run format        # prettier --write .

Haz una prueba de humo del servidor construido contra una propiedad real:

GOOGLE_SERVICE_ACCOUNT_KEY_PATH=/path/to/service-account.json \
GOOGLE_SEARCH_CONSOLE_SITE_URL=https://example.com/ \
npx @modelcontextprotocol/inspector node dist/index.js

CI / Publicación

El CI ejecuta format:check, lint, typecheck, test y build en Node.js 20 y 22. La publicación se realiza mediante el lanzamiento de GitHub con npm trusted publishing (OIDC, sin testigos):

npm version patch
git push --follow-tags
gh release create "v$(node -p "require('./package.json').version")" --generate-notes

Licencia

MIT © Orell Bühler