Yandex Search API

Servidor MCP de Yandex Search.API

Servidor MCP para Yandex Search API sobre REST con 7 herramientas:

• web_search
• image_search
• generative_search
• wordstat_get_top
• wordstat_get_dynamics
• wordstat_get_regions_distribution
• wordstat_get_regions_tree

El servidor lee las credenciales de la configuración de entorno del cliente MCP:

• FOLDER_ID
• API_KEY

Para desarrollo local, .env se carga automáticamente.

Características

• Utiliza solo endpoints REST (/v2/web/search, /v2/image/search, /v2/gen/search, rutas REST de Wordstat)
• Entradas de herramientas mínimas por defecto para mantener el contexto del modelo compacto
• searchType está disponible para todas las herramientas relevantes y tiene como valor predeterminado SEARCH_TYPE_COM
• La búsqueda web siempre fuerza responseFormat: FORMAT_XML
• Las herramientas web/imagen decodifican rawData desde Base64 y analizan XML en grupos estructurados
• Manejo de errores con estado y detalles claros de la API

Instalación

npm install yandex-searchapi-mcp

Ejemplo de configuración del cliente MCP

{
  "mcpServers": {
    "yandex-searchapi": {
      "command": "npx",
      "args": ["-y", "yandex-searchapi-mcp"],
      "env": {
        "FOLDER_ID": "your-folder-id",
        "API_KEY": "your-api-key"
      }
    }
  }
}

Herramientas

web_search

Use esta herramienta cuando necesite resultados clásicos de búsqueda web (enlaces + fragmentos), no una respuesta generada.

Entradas:

• query (obligatorio)
• searchType (opcional, predeterminado SEARCH_TYPE_COM)
• page (opcional)
• docsOnPage (opcional)
• familyMode (opcional)
• fixTypoMode (opcional)

Devuelve:

• groups[] con documents[] donde cada documento contiene:
  • url
  • title
  • language
  • passages
• requestId
• found

Nota: para búsqueda web, esta entrada se asigna a groupSpec.groupsOnPage en la API ascendente.

image_search

Use esta herramienta cuando necesite resultados de búsqueda de imágenes y metadatos de imágenes (enlaces de miniatura/original y dimensiones).

Entradas:

• query (obligatorio)
• searchType (opcional, predeterminado SEARCH_TYPE_COM)
• page (opcional)
• site (opcional)
• docsOnPage (opcional)
• imageSpec (opcional: format, size, orientation, color)

Devuelve:

• groups[] con documents[] donde cada documento contiene:
  • url
  • extras.image-properties (si está presente)
• requestId
• found

generative_search

Use esta herramienta cuando necesite una respuesta fundamentada lista para usar, sintetizada a partir de los resultados de búsqueda.

Entradas:

• query (obligatorio)
• searchType (opcional, predeterminado SEARCH_TYPE_COM)
• fixMisspell (opcional)
• getPartialResults (opcional)
• scope (opcional): { type: "site" | "host" | "url", values: string[] }

Devuelve solo los campos generativos principales (sin objetos contenedores):

• message
• sources
• searchQueries
• fixedMisspellQuery
• isAnswerRejected
• isBulletAnswer
• hints
• problematicAnswer

wordstat_get_top

Use esta herramienta para comprender qué consultas relacionadas buscan los usuarios en torno a una palabra clave.

Entradas:

• phrase (obligatorio)
• numPhrases (opcional, predeterminado 20)
• regions (opcional)
• devices (opcional)

Devuelve:

• totalCount
• results
• associations

wordstat_get_dynamics

Use esta herramienta para realizar un seguimiento de las tendencias de demanda a lo largo del tiempo para una palabra clave.

Entradas:

• phrase (obligatorio)
• period (opcional, predeterminado PERIOD_WEEKLY)
• fromDate (opcional, predeterminado now-30d, fecha y hora ISO)
• toDate (opcional, predeterminado now, fecha y hora ISO)
• regions (opcional)
• devices (opcional)

Devuelve:

• results

wordstat_get_regions_distribution

Use esta herramienta para ver en qué regiones/ciudades una palabra clave es relativamente más popular.

Entradas:

• phrase (obligatorio)
• region (opcional, predeterminado REGION_ALL)
• devices (opcional)

Devuelve:

• results

wordstat_get_regions_tree

Use esta herramienta para obtener IDs y nombres de regiones válidos para los filtros regionales de Wordstat.

Entradas:

• ninguna

Devuelve:

• regions

Desarrollo

npm install
npm run build
npm run dev