Servidor MCP de Yandex Search.API

Servidor MCP para la API de búsqueda de Yandex 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 del entorno del cliente MCP:

• FOLDER_ID

• API_KEY

Para el 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 compacto el contexto del modelo

• 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 el XML en grupos estructurados

• Manejo de errores con estado de API y detalles claros

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

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

Entradas:

• query (obligatorio)

• searchType (opcional, por defecto 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 la búsqueda web, esta entrada se asigna a groupSpec.groupsOnPage en la API upstream.

image_search

Utilice esta herramienta cuando necesite resultados de búsqueda de imágenes y metadatos de imágenes (enlaces a miniaturas/originales y dimensiones).

Entradas:

• query (obligatorio)

• searchType (opcional, por defecto 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

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

Entradas:

• query (obligatorio)

• searchType (opcional, por defecto 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

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

Entradas:

• phrase (obligatorio)

• numPhrases (opcional, por defecto 20)

• regions (opcional)

• devices (opcional)

Devuelve:

• totalCount

• results

• associations

wordstat_get_dynamics

Utilice 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, por defecto PERIOD_WEEKLY)

• fromDate (opcional, por defecto now-30d, fecha y hora ISO)

• toDate (opcional, por defecto now, fecha y hora ISO)

• regions (opcional)

• devices (opcional)

Devuelve:

• results

wordstat_get_regions_distribution

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

Entradas:

• phrase (obligatorio)

• region (opcional, por defecto REGION_ALL)

• devices (opcional)

Devuelve:

• results

wordstat_get_regions_tree

Utilice 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