Яндекс Вордстат MCP

Яндекс Вордстат MCP는 AI 애플리케이션을 Yandex 검색 수요 통계에 연결합니다. 특정 문구가 얼마나 자주 검색되는지, 어떤 달에 관심이 증가하는지, 어떤 도시에서 주제가 더 인기 있는지 물어보세요. 어시스턴트가 Wordstat 데이터를 수집하고 결과를 설명해 드립니다. 서버는 Yandex Cloud Search API를 통해 작동하므로 Direct 광고 계정에 접근할 필요가 없습니다.

• 다섯 가지 도구. 상위 및 유사 검색어, 수요 동향, 지역별 분포, 지역 사전, API 기술 요청.

• 읽기 전용. Wordstat API는 캠페인, 광고, 키워드 및 기타 개체를 생성하지 않습니다.

• 수요와 계절성. 상위 검색어와 지역은 최근 30일을 표시하며, 동향은 원하는 기간 동안 일별, 주별 또는 월별로 구성됩니다.

• 지역 및 기기. 보고서를 특정 지역으로 좁히고 컴퓨터, 휴대폰, 태블릿의 수요를 비교할 수 있습니다.

• Direct OAuth 불필요. Search API에 필요한 것은 API 키와 Yandex Cloud 카탈로그 ID뿐입니다.

안전한 요청으로 시작하세요:

"자전거 구매"를 한 달에 얼마나 검색하며, 유사한 검색어는 무엇인가요?

서버 연결 · 시나리오 보기 · 기술 문서 열기

1분 만에 작동 확인

Related MCP server: yandex-searchapi-mcp

목차

• 빠른 시작

• 무엇을 맡길 수 있나요

• 수요 데이터 읽는 방법

• 접근 권한 얻는 방법

• 데이터를 변경할 수 있는 것

• 데이터, 한도 및 백그라운드 작업

• 기술 문서

• 지원

빠른 시작

Node.js 20 이상, Search API용 Yandex Cloud API 키, Yandex Cloud 카탈로그 ID가 필요합니다.

1. 접근 권한을 얻고 AI 애플리케이션에 서버를 추가하세요. 아래에 다섯 가지 애플리케이션에 대한 지침이 있습니다.

2. "자전거 구매"를 한 달에 얼마나 검색하며, 유사한 검색어는 무엇인가요?"라고 물어보세요.

애플리케이션 인터페이스를 통해:

1. Settings → Plugins → MCP servers를 엽니다.

2. Add server를 클릭합니다.

3. 실행 명령 npx -y mcp-yandex-wordstat@latest와 환경 변수 WORDSTAT_API_KEY, WORDSTAT_FOLDER_ID를 추가합니다.

명령줄을 통해:

codex mcp add yandex-wordstat \
  --env WORDSTAT_API_KEY=ваш_ключ \
  --env WORDSTAT_FOLDER_ID=ваш_folder_id \
  -- npx -y mcp-yandex-wordstat@latest

연결을 확인하세요:

codex mcp list

Codex 공식 문서

claude mcp add \
  --env WORDSTAT_API_KEY=ваш_ключ \
  --env WORDSTAT_FOLDER_ID=ваш_folder_id \
  --transport stdio \
  --scope user \
  yandex-wordstat \
  -- npx -y mcp-yandex-wordstat@latest

서버를 확인하세요:

claude mcp list

Claude Code 문서

Settings → Developer → Edit Config를 열고 claude_desktop_config.json에 서버를 추가하세요:

{
  "mcpServers": {
    "yandex-wordstat": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-wordstat@latest"],
      "env": {
        "WORDSTAT_API_KEY": "ваш_ключ",
        "WORDSTAT_FOLDER_ID": "ваш_folder_id"
      }
    }
  }
}

Edit Config를 사용할 수 없으면 macOS에서는 ~/Library/Application Support/Claude/claude_desktop_config.json, Windows에서는 %APPDATA%\Claude\claude_desktop_config.json을 편집하세요.

모든 프로젝트에 대해 ~/.cursor/mcp.json을 만들고, 현재 프로젝트에만 적용하려면 .cursor/mcp.json을 만드세요:

{
  "mcpServers": {
    "yandex-wordstat": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-wordstat@latest"],
      "env": {
        "WORDSTAT_API_KEY": "ваш_ключ",
        "WORDSTAT_FOLDER_ID": "ваш_folder_id"
      }
    }
  }
}

Cursor 문서

명령 팔레트를 열고 MCP: Open User Configuration을 실행하세요. mcp.json에 추가하세요:

{
  "servers": {
    "yandex-wordstat": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-wordstat@latest"],
      "env": {
        "WORDSTAT_API_KEY": "${input:wordstat_api_key}",
        "WORDSTAT_FOLDER_ID": "${input:wordstat_folder_id}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "wordstat_api_key",
      "description": "API-ключ Yandex Cloud",
      "password": true
    },
    {
      "type": "promptString",
      "id": "wordstat_folder_id",
      "description": "ID каталога Yandex Cloud"
    }
  ]
}

MCP: List Servers 명령으로 실행을 확인하세요.

VS Code 문서

무엇을 맡길 수 있나요

검색어 선정 및 수요 평가

• "이 문구를 한 달에 몇 번 검색하며, 유사한 검색어는 무엇인가요?"

• "'피자 배달' 관련 검색어를 빈도와 함께 찾아주세요."

• "내 문구가 포함된 검색어와 의미상 유사한 검색어를 분리해서 보여주세요."

계절성 이해

• "'스키'에 대한 수요를 1년간 월별로 보여주세요."

• "이 서비스에 대한 수요가 증가하거나 감소하는 주는 언제인가요?"

• "휴대폰과 컴퓨터에서의 검색어 동향을 비교하세요."

지역 비교

• "'아파트 리모델링'에 대한 관심이 평균보다 높은 도시는 어디인가요?"

• "모스크바와 상트페테르부르크의 수요를 비교하세요."

• "필요한 지역의 ID를 찾고 다음 보고서를 해당 지역으로 좁히세요."

수요 데이터 읽는 방법

top_requests는 지정된 문구를 포함하는 인기 검색어와 의미상 유사한 검색어를 표시합니다. 전체 totalCount는 최근 30일을 기준으로 합니다.

dynamics는 일별, 주별 또는 월별 세부 정보로 {date, count, share} 계열을 반환합니다. regions는 최근 30일간의 수요를 지역별로 분배하며, affinityIndex가 100%를 초과하면 평균보다 높은 관심을 의미합니다. 카운터 값은 문자열로 전달될 수 있습니다. Yandex는 JSON에서 큰 정수를 이러한 형식으로 전송합니다.

한 번의 호출은 하나의 문구에 대한 데이터만 생성합니다. 키워드 목록이 많은 경우 모든 요청을 연속으로 실행하는 대신 먼저 목록을 좁히는 것이 좋습니다. Yandex Cloud Search API 할당량은 하나의 키에 대해 공유됩니다.

접근 권한 얻는 방법

1. Yandex Cloud에서 search-api.webSearch.user 역할을 가진 서비스 계정을 만듭니다.

2. 해당 계정에 대해 yc.search-api.execute 범위의 API 키를 발급합니다. 단계는 AI Studio 문서에 설명되어 있습니다.

3. Yandex Cloud 콘솔의 카탈로그 페이지와 페이지 URL에서 카탈로그 ID(folderId)를 찾습니다.

4. 키를 WORDSTAT_API_KEY로, 카탈로그를 WORDSTAT_FOLDER_ID로 전달합니다.

서버는 Yandex Cloud Search API v2에 연결합니다. OAuth를 사용하는 기존의 별도 Wordstat API는 사용되지 않습니다. API 키는 MCP 클라이언트 구성에 일반 텍스트로 저장되므로 비밀번호처럼 취급하세요.

데이터를 변경할 수 있는 것

Yandex Wordstat에서는 아무것도 변경할 수 없습니다. raw_request를 포함한 다섯 가지 도구 모두 읽기 전용으로만 작동합니다. 기술적으로 API는 POST를 사용하지만 Wordstat에는 쓰기 엔드포인트가 없습니다. 서버는 또한 임의의 요청이 다른 호스트로 전송되는 것을 추가로 차단합니다.

데이터, 한도 및 백그라운드 작업

• 집계 데이터. 서버는 특정 광고 계정의 데이터가 아닌 검색 수요 통계를 받습니다.

• 지역 사전 캐시. 장기 실행 프로세스에서 지역 트리는 한 번 로드되고 이후 요청에서 재사용됩니다.

• 일시적 오류 시 재시도. 단일 요청의 타임아웃은 60초입니다. 서버는 429, 5xx, 네트워크 오류 또는 타임아웃 후 최대 3회 재시도하며, Retry-After를 고려하고 지연은 30초를 초과하지 않습니다.

• 백그라운드 모니터링 없음. 서버는 AI 애플리케이션이 호출할 때만 작동합니다. 애플리케이션이 예약 작업을 지원하는 경우 선택한 문구에 대한 정기 보고서를 설정할 수 있습니다.

• 익명 텔레메트리. 기본적으로 서버는 무작위 설치 ID, 이벤트 또는 도구 이름, 서버 버전, Node.js, OS 및 AI 클라이언트 버전을 전송합니다. API 키, 도구 인수, 사용자 메시지, 수요 데이터 및 환경 변수 값은 포함되지 않습니다. Ask Ads MCP 서버에 대해 비활성화하려면: ASKADS_TELEMETRY=0.

기술 문서

• MCP 기능 카탈로그 — 각 도구의 사용자 작업별 페이지.

• 모든 도구 및 매개변수

• 개발 문서

• 게시 문서

• Yandex Cloud Search API 문서

지원

오류를 발견했거나 시나리오가 부족한가요? 이슈를 생성하거나 Telegram으로 문의하세요.