Yandex Semantic Core MCP
Provides tools for collecting real Yandex Wordstat v2 data via Yandex Cloud Search API, including top queries, frequencies, dynamics, regional demand, and region tree, to support semantic core research.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Yandex Semantic Core MCPCollect semantic core for example.ru, Moscow region, exclude vacancies and free downloads."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Yandex Semantic Core MCP
MCP-сервер для сбора реальных данных Yandex Wordstat v2 и управляемого исследования семантического ядра. Работает локально через stdio, использует Yandex Cloud Search API и не требует внешних Python-пакетов.
Проект повторяет полезную архитектурную идею
ЯДрышко:
Wordstat остаётся источником частот, а подключённый AI-агент выполняет очистку,
разметку интентов, кластеризацию и подготовку отчёта. В отличие от референса,
здесь Wordstat MCP входит в сам проект, без промежуточного SaaS.
Что внутри
Возможность | MCP name | Что возвращает |
Проверка подключения |
| Готовность API и число доступных регионов |
Топ запросов |
| Реальные фразы, частоты и ассоциации за 30 дней |
Динамика |
| Дневной, недельный или месячный ряд |
Спрос по регионам |
| Частота, доля и affinity index |
Дерево регионов |
| ID и названия регионов Wordstat |
Workflow | MCP prompt | Последовательность полного исследования |
Методология | 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-клиент.
Полная настройка:
Вызвать
wordstat_get_user_info.Запустить 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 toolswordstat_get_dynamicsДинамика запросов WordstatB
Динамика частоты фразы по дням, неделям или месяцам.
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | PERIOD_MONTHLY | |
| phrase | Yes | ||
| toDate | No | YYYY-MM-DD or RFC3339 | |
| devices | No | ||
| regions | No | ||
| fromDate | No | YYYY-MM-DD or RFC3339 |
TDQS
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.
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.
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.
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.
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.
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 фразы по городам или регионам.
| Name | Required | Description | Default |
|---|---|---|---|
| phrase | Yes | ||
| region | No | REGION_ALL | |
| devices | No |
TDQS
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.
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.
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.
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.
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.
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 и названия регионов для фильтров остальных инструментов.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No |
TDQS
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.
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.
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.
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.
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.
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, сервер их не вычисляет.
| Name | Required | Description | Default |
|---|---|---|---|
| phrase | Yes | ||
| devices | No | ||
| regions | No | ||
| numPhrases | No |
TDQS
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.
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.
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.
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.
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.
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 ЯДрышко.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
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.
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.
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.
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.
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.
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.
5 tool updates
v0.1.0- First observed
wordstat_get_dynamics - First observed
wordstat_get_regions - First observed
wordstat_get_regions_tree - First observed
wordstat_get_top_requests - First observed
wordstat_get_user_info
TDQS
Scored across 5 tools
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.
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.
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.
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
Keyword data, web extraction and public social search for marketing research workflows.
MCP for Yandex Direct: manage ad campaigns & analytics from Claude or ChatGPT
Read-only Yandex Metrika MCP. Query visits, sources, geo, devices and more in plain language.
Query your SEO data in plain language: rankings, audits, backlinks, competitors and AI visibility.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceEnables 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.-
- AlicenseAqualityDmaintenanceProvides tools for web, image, generative search, and Wordstat keyword statistics via Yandex Search API.75 npm1MIT
- AlicenseAqualityAmaintenanceEnables querying Yandex Wordstat search statistics, including frequency, related queries, seasonality, and regional distribution, through natural language in AI clients.570 npm5MIT
- AlicenseNot gradedqualityBmaintenanceConnects 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.1MIT