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 часа для дерева регионов)

Инструменты

Инструмент	Описание
`get-regions-tree`	Дерево регионов (топ-N уровней)
`get-region-children`	Дочерние регионы конкретного региона
`top-requests`	Популярные запросы по ключевому слову (30 дней) + похожие
`dynamics`	Динамика поисковых запросов (день/неделя/месяц)
`regions`	Региональное распределение с индексом аффинитивности

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

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

В консоли Yandex Cloud создайте сервисный аккаунт с ролью search-api.webSearch.user
Создайте API-ключ с областью yc.search-api.execute
Запишите folder ID

2. Настройка

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

3. Запуск

docker compose up -d --build

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

curl http://localhost:8000/docs

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

Откройте Admin Settings → External Tools в Open WebUI
Нажмите + (Add Server)
Type: OpenAPI (mcpo отдаёт именно OpenAPI, не MCP)
URL: http://<IP-сервера>:8000
Auth: Bearer
Key: значение MCPO_API_KEY из .env
Сохраните. Проверьте подключение кнопкой Verify Connection

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

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

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

Кэширование

Данные	TTL
Дерево регионов	24 часа
Top requests	1 час
Dynamics	1 час
Regional distribution	1 час

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

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

Переменная	Описание	Обязательно
`YANDEX_SEARCH_API_KEY`	API-ключ Yandex Cloud	✅
`YANDEX_FOLDER_ID`	ID каталога Yandex Cloud	✅
`MCPO_API_KEY`	Bearer-ключ для доступа к mcpo	✅
`MCPO_PORT`	Порт mcpo (по умолчанию 8000)	❌

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

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

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

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

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

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

ghcr.io/<username>/yandex_mcp:latest

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

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.

На хостинге используйте готовый образ — укажите 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