yandex-mcp

Yandex Webmaster, Yandex Direct, Yandex Metrika API를 AI 어시스턴트(Claude Desktop, Claude Code, Cursor 등)의 도구로 노출하는 MCP 서버입니다.

이 서버를 사용하면 어시스턴트가 자연어로 Yandex SEO, 광고 및 분석 데이터를 다룰 수 있습니다. 검색어 조회, 인덱싱 및 사이트맵 관리, 재크롤링 요청, 진단 실행, 쓰기 안전장치가 적용된 Direct 캠페인 관리, 트래픽/전환/광고 통계 조회 등을 Yandex 웹 UI에 로그인하지 않고 수행할 수 있습니다.

• 125개 도구 총: Webmaster 52개, Direct 46개, Metrika 25개, 프로젝트 관리 2개.

• 6개 MCP 프롬프트 — 이미 준비된 워크플로(캠페인 감사, 주간 보고서, 캠페인 시작, 예산 조정, SEO 감사, 학습 확인)로, autostrategies playbook을 기반으로 구축되었으며 이 플레이북은 yandex://playbook MCP 리소수로도 노출됩니다.

• 단일 서버, 다중 프로젝트: 하나의 stdio 프로세스에서 여러 Yandex 계정/토큰을 처리합니다.

• TypeScript / Node ≥ 22, @modelcontextprotocol/sdk 및 zod 기반.

작동 방식

src/index.ts는 하나의 McpServer를 부팅하고 src/webmaster/ 및 src/direct/의 모든 도구 그룹을 등록합니다. 모든 요청은 프로젝트별 HTTP 클라이언트인 src/client.ts를 거치며, 이 클라이언트는 다음 작업을 수행합니다.

• Authorization: OAuth <token> 헤더를 첨부합니다(Direct에서는 Bearer).

• Webmaster 호출은 api.webmaster.yandex.net으로, Direct 호출은 api.direct.yandex.com/json/v5로 라우팅합니다(direct.sandbox가 활성화된 경우 Direct Sandbox로).

• Webmaster user_id를 확인/캐시하고 경로에 host_id를 주입합니다.

• 네트워크 오류/429 시 순위 exponential backoff로 재시도하고 204 No Content를 처리합니다.

• Direct의 본문 내 {"error": {...}} 응답을 표시하고 Units 로컬 헤더를 추적합니다.

Related MCP server: Yandex Wordstat MCP

사전 요구사항

• Node.js ≥ 22.

• Webmaster 및/또는 Metrika API 접근 권한이 있는 Yandex OAuth 토큰.

OAuth 토큰 발급

1. Yandex OAuth 콘솔에서 애플리케이션을 등록하고 Webmaster(webmaster:hostinfo, webmaster:verify) 및/또는 Metrika(metrika:read/metrika:write) 권한 범위를 부여합니다.

2. OAuth 흐름을 통해 계정의 토큰을 획득합니다.

참고:

• Direct는 자체 애플리케이션 범위와 앱 등록 후 Direct 계정에서 제출한 승인된 접근 요청(заявка)이 필요합니다 — 기존 Webmaster/Metrika 토큰은 재발급 없이 Direct에서 사용할 수 없습니다. 접근이 승인될 때까지는 프로젝트 구성에서 direct.sandbox: true를 설정한 Direct Sandbox를 사용하세요.

• Webmaster OAuth 토큰은 6개월 후 만료되므로 재발급해야 합니다.

설치

npm install
cp .env.example .env      # then put your token in .env
npm run build

.env:

YANDEX_OAUTH_TOKEN=your_oauth_token_here

실행

npm start          # runs dist/index.js (requires build)
npm run dev        # tsx watch mode against src/index.ts

서버는 stdio를 통해 MCP를 통신신되므로, 주로 MCP 클라이언트가 실중합니다직접 실해하지 않습니다.

멀티 프학터 구성

The server can serve several projects, each with its own Yandex login/token. projects.example.json를 projects.json(에 gitignore 대상)로 복让 and copy합니다. Alternatively, YANDEX_PROJECTS_CONFIG를 다른 경로 지정할 수 있습니다. YANDEX_OAUTH_TOKEN there is no config file, a default project is used.

yandex_set_active_project로 active project를 전환하거나, yandex_projects_list로 프로젝트 목록를 확인하거나, Direct/Metrika 도모에 project를 전달하세요. Metrika 도구는 project's default_counter도 시용합니다.

프로젝트별 Direct 설정: sandbox(을 을을 )(agency) client_login(AI) limits` — 쓰기 도구 byAmount enforced through write tools to guard budget/bid changes in %.

MCP 클라이언트 연결

YANDEX_OAUTH_TOKEN env variable에서 token을 load합니다.

Claude Desktop / Cursor

MCP servers 설정(claude_desktop_config.json or equivalent)에 now add:

{
  "mcpServers": {
    "yandex": {
      "command": "node",
      "args": ["/absolute/path/to/yandex/dist/index.js"],
      "env": {
        "YANDEX_OAUTH_TOKEN": "your_oauth_token_here"
      }
    }
  }
}

Claude Code

claude mcp add yandex --env YANDEX_OAUTH_TOKEN=your_token -- node /absolute/path/to/yandex/dist/index.js

도구

Webmaster (52)

All names are yandex_webmaster_ prefixes appended. — 모든 이름은 yandex_webmaster_ 접두어가 붙습니다.

Direct (43)

All name are prefixed yandex_direct_. Write tools preview a diff unless confirm: true is set, and enforce per-project budget/bid files (you can override it with force: true). If direct.sandbox: true is set in the project, requests are sent to Directive Sandbску. Write results include a per-item summary — Directr reports partial failures inside a successful HTTP response, so check partial_failure.

프로젝트 관리 주(2)

과목 management (2) uses yprojects_list, `yandandex_set_active_project``; see Multi-project configuration.

Metrika (22)

yandex_metrika_ after all names. The stat tools accept direct_client_logins for advertising reports (ym:ad: metrics — Direct costs joined with on-site behavior), and extra_params for any other query parameter.

The reporting tools mirrors the Metrika Reporting API. Metrics and dimensions use the ym:s: (visits) / ym:pv: (pageviews) namespaces — e.g. metrics: "ym:s:visits,ym:s:users,ym:s:bounceRate", dimensions: "ym:s:date,ym:s:lastTrafficSource". Dates accept YYYY-MM-DD or relative keywords (today, yesterday, 7daysAgo). Counter-scoped tools default to the project's default_counter if counter_id/ids is omitted.

Project layout

src/
  index.ts            # entry point: boots the MCP server, registers all tools
  client.ts           # per-project HTTP client (auth schemes, base URLs, retries, Direct transport)
  projects.ts         # project registry: per-project tokens, Direct config, limits
  server-tools.ts     # project management tools (list / set active)
  webmaster/          # 14 modules, 51 Webmaster tools
  metrika/            # management + Reporting API — 10 Metrika tools
  direct/             # read, guarded write, reports — 14 Direct tools

Scripts

라이선스

MIT © Minas Sarkisyan