MCP-сервер Yandex Search.API

MCP-сервер для Yandex Search API через REST с 7 инструментами:

• web_search

• image_search

• generative_search

• wordstat_get_top

• wordstat_get_dynamics

• wordstat_get_regions_distribution

• wordstat_get_regions_tree

Сервер считывает учетные данные из конфигурации окружения MCP-клиента:

• FOLDER_ID

• API_KEY

Для локальной разработки .env загружается автоматически.

Возможности

• Использует только REST-эндпоинты (/v2/web/search, /v2/image/search, /v2/gen/search, REST-пути Wordstat)

• Минимальные входные данные инструментов по умолчанию для экономии контекста модели

• searchType доступен для всех соответствующих инструментов и по умолчанию равен SEARCH_TYPE_COM

• Веб-поиск всегда принудительно использует responseFormat: FORMAT_XML

• Инструменты для веб-поиска и поиска изображений декодируют rawData из Base64 и парсят XML в структурированные группы

• Обработка ошибок с четким статусом API и деталями

Установка

npm install yandex-searchapi-mcp

Пример конфигурации MCP-клиента

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

Инструменты

web_search

Используйте этот инструмент, когда вам нужны классические результаты веб-поиска (ссылки + сниппеты), а не сгенерированный ответ.

Входные данные:

• query (обязательно)

• searchType (опционально, по умолчанию SEARCH_TYPE_COM)

• page (опционально)

• docsOnPage (опционально)

• familyMode (опционально)

• fixTypoMode (опционально)

Возвращает:

• groups[] с documents[], где каждый документ содержит:

  • url

  • title

  • language

  • passages

• requestId

• found

Примечание: для веб-поиска этот ввод сопоставляется с groupSpec.groupsOnPage в вышестоящем API.

image_search

Используйте этот инструмент, когда вам нужны результаты поиска изображений и метаданные изображений (ссылки на миниатюры/оригиналы и размеры).

Входные данные:

• query (обязательно)

• searchType (опционально, по умолчанию SEARCH_TYPE_COM)

• page (опционально)

• site (опционально)

• docsOnPage (опционально)

• imageSpec (опционально: format, size, orientation, color)

Возвращает:

• groups[] с documents[], где каждый документ содержит:

  • url

  • extras.image-properties (если присутствует)

• requestId

• found

generative_search

Используйте этот инструмент, когда вам нужен готовый обоснованный ответ, синтезированный из результатов поиска.

Входные данные:

• query (обязательно)

• searchType (опционально, по умолчанию SEARCH_TYPE_COM)

• fixMisspell (опционально)

• getPartialResults (опционально)

• scope (опционально): { type: "site" | "host" | "url", values: string[] }

Возвращает только основные генеративные поля (без объектов-оберток):

• message

• sources

• searchQueries

• fixedMisspellQuery

• isAnswerRejected

• isBulletAnswer

• hints

• problematicAnswer

wordstat_get_top

Используйте этот инструмент, чтобы понять, какие связанные запросы пользователи ищут вокруг ключевого слова.

Входные данные:

• phrase (обязательно)

• numPhrases (опционально, по умолчанию 20)

• regions (опционально)

• devices (опционально)

Возвращает:

• totalCount

• results

• associations

wordstat_get_dynamics

Используйте этот инструмент для отслеживания трендов спроса на ключевое слово с течением времени.

Входные данные:

• phrase (обязательно)

• period (опционально, по умолчанию PERIOD_WEEKLY)

• fromDate (опционально, по умолчанию now-30d, ISO datetime)

• toDate (опционально, по умолчанию now, ISO datetime)

• regions (опционально)

• devices (опционально)

Возвращает:

• results

wordstat_get_regions_distribution

Используйте этот инструмент, чтобы увидеть, в каких регионах/городах ключевое слово относительно более популярно.

Входные данные:

• phrase (обязательно)

• region (опционально, по умолчанию REGION_ALL)

• devices (опционально)

Возвращает:

• results

wordstat_get_regions_tree

Используйте этот инструмент для получения действительных ID и названий регионов для региональных фильтров Wordstat.

Входные данные:

• нет

Возвращает:

• regions

Разработка

npm install
npm run build
npm run dev