Skip to main content
Glama
zaborlux

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

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

ParametersJSON Schema
NameRequiredDescriptionDefault
periodNoPERIOD_MONTHLY
phraseYes
toDateNoYYYY-MM-DD or RFC3339
devicesNo
regionsNo
fromDateNoYYYY-MM-DD or RFC3339

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the output essence and gives no details about date-range handling, default period, required permissions, pagination, or return shape. This is thin for an unannotated tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One short sentence, front-loaded with the key value proposition and the main aggregation options. Every word earns its place; no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 6 parameters, no output schema, and no annotations, a one-line description leaves an agent without guidance on device/region filtering, date ranges, defaults, or expected results. It is barely adequate for correct invocation beyond the required phrase parameter.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 33% (toDate/fromDate have descriptions). The phrase 'по дням, неделям или месяцам' maps to the period parameter but adds nothing about phrase, devices, regions, or date semantics, so it fails to compensate for the schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description conveys 'frequency dynamics of a phrase aggregated by day/week/month', which clearly differentiates it from sibling tools about user info, regions, and top requests. It lacks an explicit verb but the noun phrase is unambiguous enough for an agent to know what resource and operation are involved.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: this tool is for tracking temporal frequency trends of a phrase. However, there is no explicit when-to-use versus alternatives, no exclusions, and differentiation from siblings relies on their titles rather than stated criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

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

ParametersJSON Schema
NameRequiredDescriptionDefault
phraseYes
regionNoREGION_ALL
devicesNo

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states what data is produced (frequency, share, affinity index) but says nothing about how the data is aggregated, what a response looks like, whether the query is read-only, or how device/region filters affect results. The description is too thin to make agent behavior predictable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence with no filler, and the key metric outputs are front-loaded. It earns a high score for brevity, though it sacrifices useful detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations, no output schema, and 0% schema description coverage, the tool is under-specified for an agent to invoke confidently. The description does not explain the region enum values, the devices array behavior, response structure, or how this relates to sibling wordstat tools. A complete definition would need at least one more sentence of usage and output context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but it only vaguely references the phrase ('фразы') and the region dimension ('по городам или регионам'). It adds no meaning for the 'devices' parameter, and none of the enum values are explained. This leaves two of three parameters underspecified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource ('regions/cities') and the specific metrics returned ('frequency, share, affinity index'), so an agent can understand the tool's purpose. It does not use an explicit verb like 'get' or 'return', but the title 'Распределение спроса по регионам' reinforces the function. It is distinguishable from siblings by the metric focus, though it does not explicitly contrast with wordstat_get_regions_tree.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool versus any sibling, such as wordstat_get_dynamics or wordstat_get_regions_tree. There is no mention of exclusions, prerequisites, or typical use cases. The context is only implied by the metrics it returns.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

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

ParametersJSON Schema
NameRequiredDescriptionDefault
depthNo

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral burden. It discloses the main behavior ('Возвращает ID и названия регионов') and implies a read-only operation, but it does not mention the tree structure or any side-effect/auth considerations. Basic but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with no filler. The purpose is front-loaded and every word contributes meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple, but without an output schema or annotations the description should clarify that the result is a hierarchical tree and how 'depth' affects it. It states the return kind and purpose, yet leaves ambiguity versus the sibling 'wordstat_get_regions'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%: the description never mentions the 'depth' parameter. The schema itself documents type, default, min, and max, but the description does not explain what depth controls (e.g., nesting level of the tree), so it fails to compensate for the low coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Возвращает') and names the resource ('ID и названия регионов'), plus the intended use ('для фильтров остальных инструментов'). However, it does not explicitly distinguish this tree variant from the sibling tool wordstat_get_regions, so it misses the top score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the use case: retrieve region IDs to filter other tools. It gives no explicit when-to-use versus when-not-to-use guidance and names no alternatives, leaving sibling differentiation to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

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

ParametersJSON Schema
NameRequiredDescriptionDefault
phraseYes
devicesNo
regionsNo
numPhrasesNo

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden. It adds useful context: frequencies are supplied by Yandex Wordstat, not computed by the server, and the time window is explicitly 30 days. However, it omits any details about authentication, rate limits, or response format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with the core purpose front-loaded. Every clause adds value, and there is no redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has four parameters and no output schema, yet the description only covers the general purpose and a single behavioral note. It fails to explain filter semantics (devices, regions) or the output shape, leaving significant gaps for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It only implies the 'phrase' parameter ('для фразы') and says nothing about 'devices', 'regions', or 'numPhrases'. This leaves most parameters semantically undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the resource ('popular and related queries for a phrase') and a specific time window ('last 30 days'). It clearly differentiates from sibling tools like dynamics and regions, and the intent (retrieve top requests) is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus the sibling tools. It does not mention alternatives, exclusions, or prerequisites, leaving the agent to infer usage purely from the tool name and context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

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

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral burden. It does state the operation is a check, implying a non-mutating, read-only behavior, and it lists what is verified. However, it does not disclose what happens on success or failure, whether any side effects exist, or what response the agent should expect.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: the first sentence delivers the core purpose, and the second adds workflow-compatibility context. Both sentences are short, but the workflow reference is somewhat vague and could be seen as non-essential. Still, it is efficient and well front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter access-check tool, the description covers the essential invocation context: what is checked and against what service. It lacks an explicit statement about return values, but no output schema exists and the absence is less critical for a simple check operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the schema is fully covered by the empty properties object. The description adds useful context about what is being checked internally (API key, folder ID, role), which is not expressed in the schema. Baseline 4 applies because there are no parameters to document.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('проверяет') and names the exact resources checked: API key, folder ID, role, and Wordstat v2 availability. This clearly distinguishes it from the sibling data-retrieval tools (top requests, dynamics, regions), which all fetch analytics data rather than verify access.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The purpose implies usage: an agent would call this to verify credentials and access before using Wordstat data tools. However, there is no explicit when-to-use or when-not-to-use guidance, and no mention of alternatives. The 'Совместимое имя для workflow ЯДрышко' note hints at workflow context but does not provide clear usage rules.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 5 tool updatesv0.1.0
    • First observedwordstat_get_dynamics
    • First observedwordstat_get_regions
    • First observedwordstat_get_regions_tree
    • First observedwordstat_get_top_requests
    • First observedwordstat_get_user_info

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
    5 npm
    1
    MIT
  • A
    license
    A
    quality
    A
    maintenance
    Enables querying Yandex Wordstat search statistics, including frequency, related queries, seasonality, and regional distribution, through natural language in AI clients.
    5
    70 npm
    5
    MIT
  • A
    license
    Not graded
    quality
    B
    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.
    1
    MIT