7가지 도구를 포함하는 REST 기반 Yandex Search API용 MCP 서버:
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, Wordstat REST 경로)
모델 컨텍스트를 간결하게 유지하기 위해 기본 도구 입력 최소화
모든 관련 도구에서 searchType을 사용할 수 있으며 기본값은 SEARCH_TYPE_COM입니다.
웹 검색은 항상 responseFormat: FORMAT_XML을 강제합니다.
웹/이미지 도구는 Base64에서 rawData를 디코딩하고 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 (선택 사항)
반환값:
documents[]를 포함하는 groups[] (각 문서에는 다음이 포함됨):
url
title
language
passages
requestId
found
참고: 웹 검색의 경우 이 입력값은 업스트림 API의 groupSpec.groupsOnPage에 매핑됩니다.
image_search이미지 검색 결과 및 이미지 메타데이터(썸네일/원본 링크 및 크기)가 필요할 때 이 도구를 사용하세요.
입력값:
query (필수)
searchType (선택 사항, 기본값 SEARCH_TYPE_COM)
page (선택 사항)
site (선택 사항)
docsOnPage (선택 사항)
imageSpec (선택 사항: format, size, orientation, color)
반환값:
documents[]를 포함하는 groups[] (각 문서에는 다음이 포함됨):
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 날짜 시간)
toDate (선택 사항, 기본값 now, ISO 날짜 시간)
regions (선택 사항)
devices (선택 사항)
반환값:
results
wordstat_get_regions_distribution키워드가 상대적으로 더 인기 있는 지역/도시를 확인할 때 이 도구를 사용하세요.
입력값:
phrase (필수)
region (선택 사항, 기본값 REGION_ALL)
devices (선택 사항)
반환값:
results
wordstat_get_regions_tree지역별 Wordstat 필터에 사용할 유효한 지역 ID와 이름을 가져올 때 이 도구를 사용하세요.
입력값:
없음
반환값:
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.
