mcp-yandex-webmaster

Yandex Webmaster MCP

Yandex Webmaster MCP conecta aplicaciones de IA — Claude, Cursor, Codex y otras — con los datos de Yandex Webmaster. Pregunta en lenguaje natural cómo se ve tu sitio en la búsqueda de Yandex: qué páginas entraron o no entraron en la búsqueda, qué ocurre con las impresiones y los clics, qué problemas detecta Webmaster, cómo están organizados el sitemap y los enlaces externos. La conexión comienza directamente en el diálogo: no necesitas crear un token de antemano ni editar la configuración.

• 20 herramientas. Sitios, diagnóstico, consultas de búsqueda, indexación, sitemap, enlaces externos y conexión de la cuenta directamente desde el diálogo.
• Funciona con la búsqueda orgánica. No es Metrika, ni Wordstat, ni un panel publicitario: aquí no hay datos de tráfico, demanda de búsqueda ni publicidad.
• Conexión en el chat. Yandex abrirá la página de inicio de sesión; el código de un solo uso es válido durante 10 minutos y el servidor verificará el acceso a los sitios inmediatamente después de la conexión.
• Casi todo es lectura. Algunas herramientas pueden añadir un sitio o un sitemap, iniciar la confirmación de derechos o poner una página en la cola de recrawling.
• Solo tus sitios. El servidor ve los datos de los sitios a los que el token tiene acceso; para estadísticas y diagnóstico, los derechos sobre el sitio deben estar confirmados en Webmaster.

Prueba con este primer mensaje:

¿Qué problemas críticos ve ahora el diagnóstico en mi sitio?

Conectar servidor · Ver escenarios · Abrir documentación técnica

Ver el funcionamiento en un minuto

Tú: Muestra mis sitios en Webmaster y evalúa brevemente su estado.

Asistente: Muestra los sitios disponibles con el token, su IKS, el número de páginas en la búsqueda y las páginas excluidas, así como la cantidad de problemas según su gravedad.

Tú: ¿Qué problemas críticos tiene el sitio principal y qué debo revisar primero?

Asistente: Analiza el diagnóstico actual de Webmaster, separa los problemas críticos de las recomendaciones y explica cuáles requieren acciones en el sitio.

Tú: ¿Por qué consultas se mostró más el sitio durante la última semana?

Asistente: Muestra las consultas con impresiones, clics y posiciones medias. Si es necesario, compara la dinámica para computadoras y dispositivos móviles.

Contenido

• Inicio rápido
• Qué se puede encargar
• Cómo funciona
• Qué puede modificar los datos
• Conexión y configuración
• Datos y telemetría
• Limitaciones
• Documentación técnica
• Soporte

Inicio rápido

Se necesita Node.js 20+. npx descargará el servidor en el primer inicio; no es necesario instalar el paquete por separado. No necesitas obtener un token de antemano: la conexión se realiza directamente en el diálogo.

1. Añade el servidor a tu aplicación de IA. Elige la instrucción correspondiente abajo.
2. Escribe: «Conecta Yandex Webmaster» — el asistente te guiará a través del inicio de sesión en Yandex y verificará que ve tus sitios.
3. Haz tu primera pregunta, por ejemplo: «¿Qué problemas críticos ve ahora el diagnóstico en mi sitio?»

Para CI e instalaciones automáticas, puedes configurar un token ya listo — consulta Conexión y configuración.

codex mcp add yandex-webmaster \
  -- npx -y mcp-yandex-webmaster@latest

claude mcp add --transport stdio --scope user \
  yandex-webmaster -- npx -y mcp-yandex-webmaster@latest

{
  "mcpServers": {
    "yandex-webmaster": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-webmaster@latest"]
    }
  }
}

{
  "mcpServers": {
    "yandex-webmaster": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-webmaster@latest"]
    }
  }
}

{
  "servers": {
    "yandex-webmaster": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-webmaster@latest"]
    }
  }
}

Qué se puede encargar

Entender el estado del sitio en la búsqueda

• «Muestra mis sitios en Webmaster y su IKS».
• «¿Cuántas páginas del sitio principal están en la búsqueda y cuántas están excluidas?»
• «¿Qué problemas críticos y fatales hay en el sitio?»
• «¿Qué páginas importantes cambiaron su estado de indexación?»

Analizar las consultas de búsqueda

• «¿Por qué consultas se mostró más el sitio durante la última semana?»
• «¿Cómo cambiaron las impresiones, los clics y la posición media del sitio durante el último mes?»
• «Compara la visibilidad del sitio en dispositivos móviles y computadoras».

Verificar el rastreo, el sitemap y los enlaces externos

• «Muestra qué errores HTTP encontró el robot de Yandex al rastrear el sitio».
• «¿Hay errores en el sitemap y cuándo fue la última vez que el robot lo leyó?»
• «Muestra ejemplos de enlaces externos hacia el sitio».

Preparar una acción en el sitio

• «Verifica si el sitemap https://example.com/sitemap.xml, está añadido y explica qué cambiará al añadirlo».
• «¿Cuántos recrawls quedan hoy para el sitio y puedo enviar una página a la cola?»
• «¿Cómo confirmar los derechos sobre un sitio nuevo mediante DNS?»

Cómo funciona

El trabajo comienza con la lista de sitios. Cada uno tiene un identificador técnico host_id — el servidor lo toma de tu solicitud o de la variable YANDEX_WEBMASTER_HOST_ID, si está definida.

Después de confirmar los derechos sobre el sitio, el servidor puede reunir en un solo diálogo:

• estado en la búsqueda — IKS, número de páginas en la búsqueda y excluidas, problemas actuales;
• visibilidad por consultas — impresiones, clics y posiciones medias por fechas y tipos de dispositivos;
• rastreo e indexación — códigos HTTP durante el rastreo, estado de páginas importantes, sitemap y cola de recrawling;
• perfil de enlaces — ejemplos de páginas que enlazan a tu sitio.

Si no hay derechos sobre el sitio, Webmaster devolverá HOST_NOT_VERIFIED. Si el sitio aún no se ha cargado o no está indexado, HOST_NOT_LOADED y HOST_NOT_INDEXED significan que aún no hay datos, no que los indicadores sean cero.

Qué puede modificar los datos

La mayoría de las preguntas al servidor solo leen datos. Las siguientes operaciones cambian el estado en Yandex Webmaster:

Las herramientas que modifican el estado están marcadas para la aplicación de IA como acciones, y raw_request con posible eliminación, como potencialmente irreversible. La aplicación puede solicitar confirmación, pero su comportamiento depende del cliente específico. Para eliminar se necesita una solicitud explícita.

Conexión y configuración

El servidor accede a Yandex Webmaster API v4 en nombre de tu cuenta de Yandex y ve los mismos sitios que están disponibles para esa cuenta en la interfaz web de Webmaster.

Para el uso habitual no se necesita un token de antemano:

1. En el chat, pide conectar Yandex Webmaster.
2. Abre el enlace de Yandex OAuth con la cuenta que ve los sitios necesarios en Webmaster.
3. Confirma el acceso y envía el código mostrado al asistente. El código es de un solo uso, válido durante 10 minutos y se convierte en token solo dentro del servidor en ejecución — no necesitas reiniciar la aplicación ni editar la configuración.

El servidor usa PKCE: el código del chat no se puede canjear por un token por sí solo, por lo que enviarlo en el chat es seguro. El token obtenido se almacena localmente en ~/.config/mcp-yandex-webmaster/credentials.json con permisos solo para el propietario (0600). La conexión sigue funcionando sola: el acceso se renueva automáticamente y no caduca al año. Para verificar el estado, pide «muestra el estado de la conexión»; para desconectar, «desconecta Webmaster»; el acceso emitido se revoca en Yandex ID.

Para CI e instalaciones especiales, la configuración está disponible mediante variables de entorno:

Puedes obtener un token ya listo para YANDEX_OAUTH_TOKEN de la siguiente manera: crea una aplicación en oauth.yandex.ru, en los permisos de acceso elige API de Yandex Webmaster y obtén el token según la instrucción de Yandex OAuth. Esa misma aplicación servirá también para el inicio de sesión desde el diálogo — indica su ClientID en YANDEX_WEBMASTER_OAUTH_CLIENT_ID (Redirect URI — https://oauth.yandex.ru/verification_code).

No publiques el token en el chat, en repositorios ni en capturas de pantalla: da acceso a los sitios de tu cuenta.

Datos y telemetría

Por defecto, el servidor envía eventos técnicos anónimos: un identificador aleatorio de instalación, el nombre de la herramienta invocada, las versiones del servidor, de la aplicación de IA, de Node.js y del sistema operativo. El token de Yandex, los datos de la cuenta, los argumentos de las herramientas, los textos de las solicitudes, los valores y nombres de las variables de entorno no se envían.

Para desactivar la telemetría para los servidores MCP de Ask Ads, define la variable de entorno:

ASKADS_TELEMETRY=0

Limitaciones

• Los derechos confirmados son obligatorios para las estadísticas. Sin ellos, están disponibles la lista de sitios y la verificación del estado de los derechos, pero no el diagnóstico, las solicitudes ni la indexación.
• El re-rastreo está limitado por la cuota diaria del sitio. En la respuesta está quota_remainder — el saldo restante para hoy. Con 429 QUOTA_EXCEEDED esperar no ayudará: la cuota se restablecerá mañana.
• Las consultas populares están limitadas por los datos de Webmaster. En el top entran hasta 3 000 consultas de la última semana, y en una sola solicitud se pueden obtener hasta 500 filas.
• Los reintentos de solicitudes están previstos solo para errores temporales. El servidor hace hasta tres reintentos para límites de frecuencia comunes; los errores de red y del servidor solo se reintentan al leer, para no duplicar la acción.
• No hay monitoreo constante. El servidor funciona cuando la aplicación de IA lo invoca. Si la aplicación admite tareas programadas, se puede configurar una solicitud periódica al servidor para verificar las métricas necesarias.

Documentación técnica

• Todas las herramientas — parámetros, respuestas y ejemplos de llamadas.
• Desarrollo — estructura del proyecto y trabajo con el código fuente.
• Paquete en npm.
• Documentación de la API de Yandex Webmaster — fuente original sobre la API y sus limitaciones.

Soporte

¿Encontraste un error o falta un escenario? Crea un issue o escribe a Telegram.