Skip to main content
Glama
Yandex Semantic Core MCP

Yandex Semantic Core MCP

by zaborlux

Yandex Semantic Core MCP

MCP-сервер для сбора реальных данных Yandex Wordstat v2 и управляемого исследования семантического ядра. Работает локально через stdio, использует Yandex Cloud Search API и не требует внешних Python-пакетов.

Проект повторяет полезную архитектурную идею ЯДрышко: Wordstat остаётся источником частот, а подключённый AI-агент выполняет очистку, разметку интентов, кластеризацию и подготовку отчёта. В отличие от референса, здесь Wordstat MCP входит в сам проект, без промежуточного SaaS.

Что внутри

Возможность

MCP name

Что возвращает

Проверка подключения

wordstat_get_user_info

Готовность API и число доступных регионов

Топ запросов

wordstat_get_top_requests

Реальные фразы, частоты и ассоциации за 30 дней

Динамика

wordstat_get_dynamics

Дневной, недельный или месячный ряд

Спрос по регионам

wordstat_get_regions

Частота, доля и affinity index

Дерево регионов

wordstat_get_regions_tree

ID и названия регионов Wordstat

Workflow

MCP prompt semantic-core

Последовательность полного исследования

Методология

MCP resources

Правила качества, результат и настройка Yandex

Сервер не вычисляет и не дополняет частоты. Значения в ответах инструментов приходят непосредственно из Wordstat v2.

Related MCP server: yandex-searchapi-mcp

Быстрый запуск

Требуется Python 3.10 или новее.

git clone https://github.com/zaborlux/yandex-semantic-core-mcp.git
cd yandex-semantic-core-mcp
export YANDEX_SEARCH_API_KEY='ваш API key'
export YANDEX_FOLDER_ID='ваш Folder ID'
python3 server.py

При прямом запуске процесс ожидает MCP JSON-RPC в stdin. Обычно его запускает Cursor, Claude, Codex или другой MCP-клиент.

Полная настройка:

  1. Подготовить Yandex Cloud.

  2. Подключить MCP-клиент.

  3. Вызвать wordstat_get_user_info.

  4. Запустить prompt semantic-core или сформулировать задачу обычным текстом.

Пример запроса агенту

Собери семантическое ядро для https://example.ru.
Регион: Москва, Wordstat ID 213.
Цель: заявки на услугу.
Исключить: вакансии и бесплатные скачивания.
Используй prompt semantic-core и реальные данные Wordstat.

Структура

yandex-semantic-core-mcp/
├── server.py
├── pyproject.toml
├── .env.example
├── docs/
│   ├── architecture.md
│   ├── mcp-client-setup.md
│   ├── semantic-core-workflow.md
│   ├── troubleshooting.md
│   └── yandex-cloud-setup.md
├── examples/
│   └── mcp-config.json
└── tests/
    └── test_server.py

Проверка

python3 -m unittest discover -s tests -v

Проверить только MCP handshake можно без ключа:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | python3 server.py

Для обращения к Wordstat нужны Yandex Cloud API key и Folder ID.

Безопасность

  • Не коммитьте API key и не помещайте его в .env.example.

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

  • Ограничьте API key областью yc.search-api.execute.

  • Сервер не пишет ключ, Folder ID, запросы или ответы в stdout: stdout занят MCP-протоколом.

  • Сырые результаты Wordstat храните отдельно от выводов AI.

Ограничения

  • Транспорт — локальный stdio; публичного HTTP endpoint нет.

  • Обход сайта, live SERP, GSC и Яндекс Вебмастер не входят в сервер.

  • Кластеризацию делает подключённая модель по встроенной методологии; она должна явно отмечать отсутствие live SERP-проверки.

  • Использование Search API тарифицируется и ограничивается квотами Yandex Cloud.

Документы

Лицензия

MIT.

Available Tools

5 tools
wordstat_get_dynamicsДинамика запросов WordstatB

Динамика частоты фразы по дням, неделям или месяцам.

Inputs: phrase (required), period, toDate, devices, +2 more.

wordstat_get_regionsРаспределение спроса по регионамC

Частота, доля и affinity index фразы по городам или регионам.

Inputs: phrase (required), region, devices.

wordstat_get_regions_treeДерево регионов WordstatB

Возвращает ID и названия регионов для фильтров остальных инструментов.

Inputs: depth.

wordstat_get_top_requestsТоп запросов WordstatB

Популярные и связанные запросы для фразы за последние 30 дней. Частоты возвращает Yandex Wordstat, сервер их не вычисляет.

Inputs: phrase (required), devices, regions, numPhrases.

wordstat_get_user_infoПроверить доступ к WordstatA

Проверяет API key, folder ID, роль и доступность Wordstat v2. Совместимое имя для workflow ЯДрышко.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct aspect of Yandex Wordstat: auth status, top requests, time dynamics, region breakdown, and region metadata. No two tools overlap in purpose, so an agent can reliably select the right one.

    Naming Consistency5/5

    All tools follow the exact verb_noun pattern wordstat_get_*, making the naming highly predictable and consistent. The prefix also reinforces the domain, and the suffixes clearly indicate the resource or action.

    Tool Count5/5

    Five tools is a well-scoped size for a Wordstat-focused server, covering the core read-only operations without redundancy. Each tool earns its place and the set feels neither sparse nor bloated.

    Completeness5/5

    The surface covers the essential Wordstat workflow: authentication verification, request discovery, time-series dynamics, region filtering, and region metadata. There are no obvious dead ends or missing core operations for this domain.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables keyword research and search trend analysis for the Russian market through Yandex Wordstat API. Provides access to popular search queries, search volume dynamics over time, and regional distribution data.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Provides tools for web, image, generative search, and Wordstat keyword statistics via Yandex Search API.
      7
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables querying Yandex Wordstat search statistics, including frequency, related queries, seasonality, and regional distribution, through natural language in AI clients.
      5
      178 npm
      9
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects Claude or ChatGPT to Yandex Wordstat for keyword research, enabling frequency lookups, related phrase suggestions with noise filtering, and 24-month seasonality analysis directly in chat.
      2
      MIT