Yandex Wordstat MCP

Yandex Wordstat MCP

Yandex Wordstat MCP conecta una aplicación de IA a las estadísticas de demanda de búsqueda de Yandex. Pregunte con qué frecuencia se busca una frase, en qué meses crece el interés y en qué ciudades el tema es más popular: el asistente recopilará los datos de Wordstat y explicará el resultado. El servidor funciona a través de Yandex Cloud Search API, por lo que no requiere acceso a la cuenta publicitaria de Direct.

• Cinco herramientas. Principales y consultas similares, dinámica de demanda, distribución por regiones, directorio de regiones y consulta técnica a la API.
• Solo lectura. La API de Wordstat no crea campañas, anuncios, frases clave ni otros objetos.
• Demanda y estacionalidad. Las principales consultas y regiones muestran los últimos 30 días; la dinámica se construye por días, semanas o meses para el período deseado.
• Región y dispositivo. Los informes se pueden limitar a una región y comparar la demanda en computadoras, teléfonos y tabletas.
• Sin OAuth de Direct. Se necesitan una clave de API y el ID de catálogo de Yandex Cloud para Search API.

Comience con una consulta segura:

¿Cuántas veces al mes se busca «comprar bicicleta» y qué consultas similares existen?

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

Ver el funcionamiento en un minuto

Contenido

• Inicio rápido
• Qué se puede encargar
• Cómo leer los datos de demanda
• Cómo obtener acceso
• Qué puede cambiar los datos
• Datos, límites y trabajo en segundo plano
• Documentación técnica
• Soporte

Inicio rápido

Se necesitan Node.js 20 o superior, una clave de API de Yandex Cloud para Search API y el ID de catálogo de Yandex Cloud.

1. Obtenga acceso y agregue el servidor a la aplicación de IA: instrucciones para cinco aplicaciones a continuación.
2. Pregunte: «¿Cuántas veces al mes se busca "comprar bicicleta" y qué consultas similares existen?»

codex mcp add yandex-wordstat \
  --env WORDSTAT_API_KEY=ваш_ключ \
  --env WORDSTAT_FOLDER_ID=ваш_folder_id \
  -- npx -y mcp-yandex-wordstat@latest

codex mcp list

claude mcp add \
  --env WORDSTAT_API_KEY=ваш_ключ \
  --env WORDSTAT_FOLDER_ID=ваш_folder_id \
  --transport stdio \
  --scope user \
  yandex-wordstat \
  -- npx -y mcp-yandex-wordstat@latest

claude mcp list

{
  "mcpServers": {
    "yandex-wordstat": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-wordstat@latest"],
      "env": {
        "WORDSTAT_API_KEY": "ваш_ключ",
        "WORDSTAT_FOLDER_ID": "ваш_folder_id"
      }
    }
  }
}

{
  "mcpServers": {
    "yandex-wordstat": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-wordstat@latest"],
      "env": {
        "WORDSTAT_API_KEY": "ваш_ключ",
        "WORDSTAT_FOLDER_ID": "ваш_folder_id"
      }
    }
  }
}

{
  "servers": {
    "yandex-wordstat": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-wordstat@latest"],
      "env": {
        "WORDSTAT_API_KEY": "${input:wordstat_api_key}",
        "WORDSTAT_FOLDER_ID": "${input:wordstat_folder_id}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "wordstat_api_key",
      "description": "API-ключ Yandex Cloud",
      "password": true
    },
    {
      "type": "promptString",
      "id": "wordstat_folder_id",
      "description": "ID каталога Yandex Cloud"
    }
  ]
}

Qué se puede encargar

Seleccionar y evaluar la demanda

• «¿Cuántas veces al mes se busca esta frase y qué consultas similares aparecen?»
• «Selecciona consultas en torno a "entrega de pizza" con su frecuencia».
• «Muestra las consultas que contienen mi frase, por separado de las semánticamente similares».

Comprender la estacionalidad

• «Muestra la demanda de "esquís" por meses durante un año».
• «¿En qué semanas crece o cae la demanda de este servicio?»
• «Compara la dinámica de la consulta en teléfonos y computadoras».

Comparar regiones

• «¿En qué ciudades el interés por "reparación de apartamentos" es superior al promedio?»
• «Compara la demanda en Moscú y San Petersburgo».
• «Encuentra el ID de la región necesaria y limita el siguiente informe a ella».

Cómo leer los datos de demanda

top_requests muestra las consultas populares que contienen la frase dada y las consultas semánticamente cercanas. El totalCount general se refiere a los últimos 30 días.

dynamics devuelve una serie de {date, count, share} con detalle diario, semanal o mensual. regions distribuye la demanda de los últimos 30 días por regiones, y un affinityIndex superior al 100% significa un interés por encima del promedio. Los valores de los contadores pueden llegar como cadenas: Yandex transmite números enteros grandes en JSON de esta forma.

Una sola llamada construye datos solo para una frase. Para una lista grande de palabras clave, es mejor primero reducir la lista en lugar de ejecutar todas las consultas seguidas: la cuota de Yandex Cloud Search API es común para una sola clave.

Cómo obtener acceso

1. En Yandex Cloud cree una cuenta de servicio con el rol search-api.webSearch.user.
2. Emita para ella una clave de API con el scope yc.search-api.execute: los pasos se describen en la documentación de AI Studio.
3. Encuentre el ID de catálogo (folderId) en la consola de Yandex Cloud en la página del catálogo y en la URL de la página.
4. Pase la clave como WORDSTAT_API_KEY y el catálogo como WORDSTAT_FOLDER_ID.

El servidor se comunica con Yandex Cloud Search API v2. La antigua API separada de Wordstat con OAuth no se utiliza. La clave de API se almacena en texto plano en la configuración del cliente MCP: trátela como una contraseña.

Qué puede cambiar los datos

Nada en Yandex Wordstat. Las cinco herramientas, incluida raw_request, funcionan solo en modo lectura. Técnicamente, la API utiliza POST, pero Wordstat no tiene endpoints de escritura; el servidor además no permite que una consulta arbitraria vaya a otro host.

Datos, límites y trabajo en segundo plano

• Datos agregados. El servidor recibe estadísticas de demanda de búsqueda, no datos de una cuenta publicitaria específica.
• Caché del directorio de regiones. En un proceso de larga duración, el árbol de regiones se carga una vez y se reutiliza en las siguientes consultas.
• Reintentos ante errores temporales. El tiempo de espera de una consulta es de 60 segundos. El servidor realiza hasta tres reintentos después de 429, 5xx, un error de red o un tiempo de espera; tiene en cuenta Retry-After, y el retraso no supera los 30 segundos.
• Sin monitoreo en segundo plano. El servidor funciona cuando la aplicación de IA lo llama. Si la aplicación admite tareas programadas, se puede configurar un informe periódico sobre las frases seleccionadas.
• Telemetría anónima. Por defecto, el servidor envía un identificador de instalación aleatorio, el nombre del evento o herramienta, las versiones del servidor, Node.js, el sistema operativo y el cliente de IA. No incluyen la clave de API, los argumentos de las herramientas, sus mensajes, los datos de demanda ni los valores de las variables de entorno. Para desactivarla en los servidores MCP de Ask Ads: ASKADS_TELEMETRY=0.

Documentación técnica

• Catálogo de capacidades MCP: páginas sobre tareas de usuario para cada herramienta.
• Todas las herramientas y parámetros
• Documentación de desarrollo
• Documentación de publicación
• Documentación de Yandex Cloud Search API

Soporte

¿Encontró un error o falta un escenario? Cree un issue o escriba en Telegram.