MCP-сервер для Yandex Search API через REST с 7 инструментами:
web_search
image_search
generative_search
wordstat_get_top
wordstat_get_dynamics
wordstat_get_regions_distribution
wordstat_get_regions_tree
Сервер считывает учетные данные из конфигурации окружения MCP-клиента:
FOLDER_ID
API_KEY
Для локальной разработки .env загружается автоматически.
Использует только REST-эндпоинты (/v2/web/search, /v2/image/search, /v2/gen/search, REST-пути Wordstat)
Минимальные входные данные инструментов по умолчанию для экономии контекста модели
searchType доступен для всех соответствующих инструментов и по умолчанию равен SEARCH_TYPE_COM
Веб-поиск всегда принудительно использует responseFormat: FORMAT_XML
Инструменты для веб-поиска и поиска изображений декодируют rawData из Base64 и парсят XML в структурированные группы
Обработка ошибок с четким статусом API и деталями
Related MCP server: Yandex Search MCP Server
npm install yandex-searchapi-mcp{
"mcpServers": {
"yandex-searchapi": {
"command": "npx",
"args": ["-y", "yandex-searchapi-mcp"],
"env": {
"FOLDER_ID": "your-folder-id",
"API_KEY": "your-api-key"
}
}
}
}web_searchИспользуйте этот инструмент, когда вам нужны классические результаты веб-поиска (ссылки + сниппеты), а не сгенерированный ответ.
Входные данные:
query (обязательно)
searchType (опционально, по умолчанию SEARCH_TYPE_COM)
page (опционально)
docsOnPage (опционально)
familyMode (опционально)
fixTypoMode (опционально)
Возвращает:
groups[] с documents[], где каждый документ содержит:
url
title
language
passages
requestId
found
Примечание: для веб-поиска этот ввод сопоставляется с groupSpec.groupsOnPage в вышестоящем API.
image_searchИспользуйте этот инструмент, когда вам нужны результаты поиска изображений и метаданные изображений (ссылки на миниатюры/оригиналы и размеры).
Входные данные:
query (обязательно)
searchType (опционально, по умолчанию SEARCH_TYPE_COM)
page (опционально)
site (опционально)
docsOnPage (опционально)
imageSpec (опционально: format, size, orientation, color)
Возвращает:
groups[] с documents[], где каждый документ содержит:
url
extras.image-properties (если присутствует)
requestId
found
generative_searchИспользуйте этот инструмент, когда вам нужен готовый обоснованный ответ, синтезированный из результатов поиска.
Входные данные:
query (обязательно)
searchType (опционально, по умолчанию SEARCH_TYPE_COM)
fixMisspell (опционально)
getPartialResults (опционально)
scope (опционально): { type: "site" | "host" | "url", values: string[] }
Возвращает только основные генеративные поля (без объектов-оберток):
message
sources
searchQueries
fixedMisspellQuery
isAnswerRejected
isBulletAnswer
hints
problematicAnswer
wordstat_get_topИспользуйте этот инструмент, чтобы понять, какие связанные запросы пользователи ищут вокруг ключевого слова.
Входные данные:
phrase (обязательно)
numPhrases (опционально, по умолчанию 20)
regions (опционально)
devices (опционально)
Возвращает:
totalCount
results
associations
wordstat_get_dynamicsИспользуйте этот инструмент для отслеживания трендов спроса на ключевое слово с течением времени.
Входные данные:
phrase (обязательно)
period (опционально, по умолчанию PERIOD_WEEKLY)
fromDate (опционально, по умолчанию now-30d, ISO datetime)
toDate (опционально, по умолчанию now, ISO datetime)
regions (опционально)
devices (опционально)
Возвращает:
results
wordstat_get_regions_distributionИспользуйте этот инструмент, чтобы увидеть, в каких регионах/городах ключевое слово относительно более популярно.
Входные данные:
phrase (обязательно)
region (опционально, по умолчанию REGION_ALL)
devices (опционально)
Возвращает:
results
wordstat_get_regions_treeИспользуйте этот инструмент для получения действительных ID и названий регионов для региональных фильтров Wordstat.
Входные данные:
нет
Возвращает:
regions
npm install
npm run build
npm run devGenerate an answer grounded in web search results, with optional source restrictions (site/host/url).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Question or task for a grounded generative answer. | |
| searchType | No | Search market/domain. Default is SEARCH_TYPE_COM (international). | |
| fixMisspell | No | Enable automatic misspelling correction for the query. | |
| getPartialResults | No | Allow partial streaming-style intermediate results. | |
| scope | No | Optional source restriction list for the generative answer. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states high-level behavior. It does not disclose potential external requests, rate limits, authentication needs, or that results are generated by an LLM. Minimal transparency.
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?
Single sentence that is front-loaded with the core action ('Generate an answer grounded in web search results'). Every word earns its place; no 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?
Given the complexity (5 params, nested object, no output schema), the description provides the core purpose and a key optional feature but lacks return format, error handling, or behavior of intermediate results. Adequate but incomplete.
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 coverage is 100%, so baseline is 3. The description highlights the scope parameter but adds no new meaning beyond what the schema already provides. Other parameters remain unelaborated.
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 clearly states the verb 'Generate' and the resource 'an answer grounded in web search results'. It also mentions optional source restrictions, distinguishing it from siblings like web_search (which returns raw results) and image_search.
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 usage when a generative answer is needed but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. Sibling tools are not contrasted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search images by text query. Returns grouped image documents and image metadata like thumbnail/original links.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | What image you want to find, for example: 'golden retriever puppy'. | |
| searchType | No | Search market/domain. Default is SEARCH_TYPE_COM (international). | |
| page | No | Results page index (0 = first page). | |
| site | No | Optional website/domain filter, for example: 'wikipedia.org'. | |
| docsOnPage | No | How many result groups to return on one page. | |
| imageSpec | No | Optional set of image-specific filters. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits like pagination, filtering, or read-only nature beyond the bare return type.
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 that efficiently convey the core purpose and output, no wasted words.
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?
Given the 6 parameters with full schema descriptions, the description is minimal but covers the main action; lacks selection context relative to siblings.
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 coverage is 100%, and the description adds context about output but does not enhance parameter meaning beyond the schema's descriptions.
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 clearly states the tool searches images by text query and returns grouped image documents with metadata, distinguishing it from sibling tools like web_search.
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 explicit guidance on when to use vs alternatives, but the purpose implies image-specific searches; it is not misleading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search web pages by text query. Returns grouped documents with URL, title, language, and snippet passages.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | What you want to find on the web, for example: 'best espresso machine' | |
| searchType | No | Search market/domain. Default is SEARCH_TYPE_COM (international). | |
| page | No | Results page index (0 = first page). | |
| docsOnPage | No | How many result groups to return on one page. | |
| familyMode | No | Adult content filtering mode. | |
| fixTypoMode | No | Whether typo autocorrection is enabled. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description should compensate. It only mentions output fields but lacks details on safety (read-only), pagination, or authentication needs. Essential behavioral traits are omitted.
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 at two sentences, front-loaded with the action and output, with no redundancy or unnecessary 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?
Given 6 parameters, no output schema, and no annotations, the description is too minimal. It fails to explain pagination, result format beyond listed fields, or how familyMode and fixTypoMode affect results.
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 descriptions cover 100% of parameters. The description does not add additional meaning beyond what the schema provides, meeting the baseline expectation.
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 clearly states the tool's action ('Search web pages by text query') and the output structure ('grouped documents with URL, title, language, and snippet passages'). It effectively distinguishes from siblings like image_search and generative_search.
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 use for text-based web search, and sibling names provide context, but no explicit when-to-use or when-not-to-use guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get how search frequency changes over time for a keyword (daily, weekly, or monthly).
| Name | Required | Description | Default |
|---|---|---|---|
| phrase | Yes | Keyword/phrase to analyze in Wordstat. | |
| period | No | Aggregation period. Default is PERIOD_WEEKLY. | |
| fromDate | No | Start datetime in ISO-8601 format. If omitted, a safe default is used. | |
| toDate | No | End datetime in ISO-8601 format. If omitted, a safe default is used. | |
| regions | No | Optional list of region IDs to filter statistics. | |
| devices | No | Optional device filter: all/desktop/phone/tablet. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits such as whether the operation is read-only, authentication requirements, rate limits, or potential side effects. For a tool that retrieves data, minimal transparency is given.
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, clear sentence with no unnecessary words. It is front-loaded with the core action and resource.
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?
No output schema is present, and the description does not explain the return format (e.g., time series data, value type). Given the tool's function (trend analysis), more contextual detail about the response would be helpful.
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 coverage is 100%, so the description adds limited value over the schema. It mentions 'daily, weekly, or monthly' which is already captured by the period enum. Baseline 3 is appropriate as no additional semantic aid is provided.
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 clearly states the verb 'Get', the resource 'search frequency changes over time for a keyword', and specifies time granularity options (daily, weekly, monthly). This distinguishes it from sibling tools like wordstat_get_top or wordstat_get_regions_distribution.
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 explicit guidance on when to use this tool versus alternatives (e.g., other wordstat tools). The context is implied but not stated, leaving the agent to infer usage from the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get regional distribution for a keyword: where users search this phrase more often.
| Name | Required | Description | Default |
|---|---|---|---|
| phrase | Yes | Keyword/phrase to analyze in Wordstat. | |
| region | No | Distribution granularity. Default is REGION_ALL. | |
| devices | No | Optional device filter: all/desktop/phone/tablet. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries full responsibility for disclosing behavioral traits. It does not mention whether the operation is read-only, what the output format is, or if any side effects exist. The 11-word description adds minimal detail beyond the tool's name.
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, front-loaded sentence that gets straight to the point. No extraneous words or filler. Every word earns its place in defining the tool's purpose.
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 description lacks explanation of the return value (no output schema provided) and does not clarify how the distribution is represented (e.g., percentages, counts). For a tool with three parameters and no output schema, more context is needed for complete understanding.
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 100%, meaning all three parameters have descriptions in the input schema. The tool description adds no additional semantic information beyond what the schema already provides. Per guidelines, baseline is 3 when coverage is high.
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 ('Get') and resource ('regional distribution') and explains the purpose ('where users search this phrase more often'). It clearly distinguishes from sibling tools like wordstat_get_dynamics (time trends) and wordstat_get_top (top queries) by focusing on geographic distribution.
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 is provided on when to use this tool versus alternatives such as wordstat_get_regions_tree or wordstat_get_dynamics. The description does not mention prerequisites, exclusions, or typical use cases, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full tree of Wordstat region IDs and names. Useful for choosing region filters.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that it returns a 'full tree' of region IDs and names, but does not mention whether the data is static, how large the tree is, or if it requires any authentication. The description is minimal but acceptable for a simple read operation.
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?
Description is two sentences, front-loaded with the main action and resource, followed by a use case. No unnecessary words.
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?
Given zero parameters, no output schema, and no annotations, the description is largely complete. However, it could benefit from briefly explaining the tree structure (e.g., nested or flat) or any limitations on region coverage.
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 schema coverage is 100%. The description adds value by explaining the output contains a 'full tree' with 'IDs and names', which gives context beyond the empty schema.
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?
Description clearly states 'Get the full tree of Wordstat region IDs and names', which specifies the action and resource. It distinguishes from siblings like wordstat_get_dynamics or wordstat_get_top by emphasizing it returns a hierarchical tree of regions.
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 phrase 'Useful for choosing region filters' gives a clear use case. However, it does not explicitly state when not to use this tool or mention alternatives like searching for a specific region.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get popular and related search queries for a keyword using Yandex Wordstat.
| Name | Required | Description | Default |
|---|---|---|---|
| phrase | Yes | Keyword/phrase to analyze in Wordstat. | |
| numPhrases | No | How many top phrases to return. Default is 20. | |
| regions | No | Optional list of region IDs to filter statistics. | |
| devices | No | Optional device filter: all/desktop/phone/tablet. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only says 'get popular and related search queries', but does not disclose whether it is a read-only operation, any authentication requirements, rate limits, or other behavioral traits.
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 one short sentence, front-loaded with the key purpose. Every word is necessary and no waste.
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 output schema and no annotations, the description fails to explain the return format, pagination, or what 'popular and related' means. For a tool with 4 parameters, this is insufficient.
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 100%, so all parameters are already documented in the schema. The description adds no extra meaning beyond what the schema provides. Baseline of 3 is appropriate as the schema does the heavy lifting.
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 clearly states the verb 'Get', the resource 'popular and related search queries for a keyword', and the system 'Yandex Wordstat'. It distinguishes from sibling tools like wordstat_get_dynamics or web_search by specifying it returns top queries for a keyword.
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 provides no guidance on when to use this tool versus its siblings or alternatives. There is no mention of prerequisites, use cases, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1generative_searchimage_searchweb_searchwordstat_get_dynamicswordstat_get_regions_distributionwordstat_get_regions_treewordstat_get_topScored across 7 tools
Each tool has a clearly distinct purpose: web search, image search, generative answer, and four distinct Wordstat analytics functions. No overlap or confusion between tools.
All tool names follow snake_case with a consistent verb_noun pattern. The three search tools use 'search' as noun, and the four Wordstat tools use 'wordstat_get_<feature>'.
7 tools is an ideal scope for a Yandex Search API server, covering core search types and keyword research without being overwhelming or insufficient.
The tool set covers web search, image search, generative search, and comprehensive Wordstat analytics. Minor gaps like video or news search exist but are not essential for the server's stated purpose.
Yandex search results, images, and SERP data via the Apify Yandex Search Scraper, hosted MCP.
Web search, page reading and structured extraction for AI agents, with strong RU coverage
Web search, AI agent, and content extraction via You.com APIs
Web search, browser automation, scraping, crawling and CAPTCHA solving for AI agents.
