Yandex Wordstat MCP для Open WebUI

MCP-сервер для работы с Yandex Wordstat v2 API (исследование ключевых слов и анализ поисковых трендов) с in-memory кэшированием, обёрнутый в mcpo-прокси для интеграции с Open WebUI.

Архитектура

Open WebUI  ──HTTP/OpenAPI──▶  mcpo (proxy)  ──stdio──▶  Node MCP Server  ──HTTPS──▶  Yandex Wordstat v2 API
                               :8000                     (with TTL cache)

• MCP-сервер (src/index.mjs) — stdio-транспорт, 5 инструментов Wordstat, TTL-кэш

• mcpo — конвертирует stdio MCP → OpenAPI HTTP (нужно для Open WebUI, который поддерживает только Streamable HTTP)

• Кэш — in-memory TTL (1 час для запросов, 24 часа для дерева регионов)

Related MCP server: Yandex AI Studio MCP Server

Инструменты

Быстрый старт

1. Получение ключей Yandex Cloud

1. В консоли Yandex Cloud создайте сервисный аккаунт с ролью search-api.webSearch.user

2. Создайте API-ключ с областью yc.search-api.execute

3. Запишите folder ID

2. Настройка

cp .env.example .env
# Отредактируйте .env — впишите ключи

3. Запуск

docker compose up -d --build

Проверьте, что сервис работает:

curl http://localhost:8000/docs

4. Подключение к Open WebUI

1. Откройте Admin Settings → External Tools в Open WebUI

2. Нажмите + (Add Server)

3. Type: OpenAPI (mcpo отдаёт именно OpenAPI, не MCP)

4. URL: http://<IP-сервера>:8000

5. Auth: Bearer

6. Key: значение MCPO_API_KEY из .env

7. Сохраните. Проверьте подключение кнопкой Verify Connection

Теперь инструменты Wordstat доступны в чате через + → Integrations → Tools.

Локальный запуск (без Docker)

npm install
YANDEX_SEARCH_API_KEY=your_key YANDEX_FOLDER_ID=your_folder node src/index.mjs

Кэширование

Максимум 500 записей в кэше, eviction по LRU.

Переменные окружения

Публикация Docker-образа (GitHub Container Registry)

Проект включает GitHub Actions workflow (.github/workflows/docker-publish.yml), который автоматически собирает и публикует образ в GHCR при пуше в main или создании тега v*.

Как опубликовать

1. Создайте репозиторий на GitHub и запушьте код:

git remote add origin https://github.com/<username>/yandex_mcp.git
git push -u origin main

2. GitHub Actions автоматически соберёт образ и опубликует его как:

ghcr.io/<username>/yandex_mcp:latest

3. Для релиза конкретной версии создайте тег:

git tag v1.0.0
git push origin v1.0.0

Это создаст образы ghcr.io/<username>/yandex_mcp:1.0.0 и ghcr.io/<username>/yandex_mcp:1.0.

4. На хостинге используйте готовый образ — укажите GHCR_OWNER в .env:

GHCR_OWNER=<username>
docker compose pull && docker compose up -d

Локальная сборка (вместо готового образа)

Если хотите собирать локально, раскомментируйте build: . в docker-compose.yml:

services:
  yandex-wordstat-mcp:
    # image: ghcr.io/...
    build: .

Лимиты

• Rate limit: 10 запросов/сек (клиентский)

• Биллинг: через Yandex Cloud (Search API)

Лицензия

MIT