Yandex Search.API MCP 서버

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 상태 및 세부 정보를 포함한 오류 처리

설치

npm install yandex-searchapi-mcp

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 dev