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

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

Кэширование

Данные	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*.

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

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