yandex-mcp

MCP サーバーで、Yandex Webmaster・Yandex Direct・Yandex Metrika の API を AI アシスタント（Claude Desktop、Claude Code、Cursor など）向けのツールとして公開します。

これにより、アシスタントが Yandex の SEO・広告・分析データを自然言語で扱えるようになります。検索クエリの確認、インデックスとサイトマップの管理、再クロールのリクエスト、診断の実行、書き込み保護ガード付きの Direct キャンペーン運用、トラフィック / コンバージョン / 広告統計の取得が、Yandex の Web UI にログインせずに行えます。

• 合計 125 ツール: Webmaster 52、Direct 46、Metrika 25、プロジェクト管理 2。

• 6 つの MCP プロンプト — 既製のワークフロー（キャンペーン監査、週次レポート、キャンペーン作成、予算拡大、SEO 監査、学習確認）で、autostrategies のプレイブック上に構築されており、yandex://playbook MCP リソースとしても公開されています。

• 単一サーバー・マルチプロジェクト: 複数の Yandex アカウント／トークンを 1 つの stdio プロセスで処理できます。

• TypeScript / Node ≥ 22、@modelcontextprotocol/sdk と zod 上に構築。

動作の仕組み

src/index.ts は 1 つの McpServer を起動し、src/webmaster/ と src/direct/ のすべてのツールグループを登録します。すべてのリクエストは src/client.ts（プロジェクトごとの HTTP クライアント）を通して処理されます。このクライアントは次のことを行います。

• 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 に対して指数バックオフで再試行し、204 No Content も処理します。

• Direct のレスポンスボディ内の {"error": {...}} を検出し、Quota クォータヘッダーを追跡します。

Related MCP server: Yandex Wordstat MCP

前提条件

• Node.js ≥ 22。

• Webmaster または/および Metrika API にアクセスできる Yandex OAuth トークン。

OAuth トークンを取得する

1. Yandex OAuth console でアプリケーションを登録し、Webmaster（webmaster:hostinfo、webmaster:verify）および/または Metrika（metrika:read / metrika:write）スコープを付与します。

2. OAuth flow を利用してアカウントのトークンを取得します。

注意:

• Direct は独自のアプリスコープと、アプリ登録後に Direct アカウントから提出された承認済みアクセスリクエスト（заявка）が必要です。既存の Webmaster/Metrika トークンは、再発行しない限り Direct では利用できません。アクセス承認までの間は、Direct Sandbox（プロジェクト設定で direct.sandbox: true）を使用してください。

• 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 クライアントから起動されます。

マルチプロジェクト構成

このサーバーは、ドのプロジェクトにも個別の Yandex ログイン/トークンを持つ、複数のプロジェクトを提供できます。 projects.example.json を projects.json（gitignore 対象）にコピーして内容を記入するか、YANDPROJECTS_CONFIG を別のパスに設定してください。設定ファイルが存在せず、YANDEX_OAUTH_TOKEN が設定されている場合は、単一のプロジェクト default が使用されます。

アクティブなプロジェクトは yandex_set_active_project で切り替え、yandex_projects_list で確認できます。また、任意の Direct または Metrika ツールに project を渡すこともできます。Metrika ツールはプロジェクトの default_counter も考慮します。

プロジェクトごとの Direct 設定: sandbox（Direct Sandbox へのルーティング）、client_login（代理店アカウント）、limits（書き込みツールによって強制される、予算／入札の最大許容変更率（％））。

MCP クライアントへの接続

トークンは YANDEX_OAUTH_TOKEN 環境変数から読み取られます。

Claude Desktop / Cursor

MCP サーバーの設定（claude_desktop_config.json など）に追加します:

{
  "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）

すべての名前には yandex_webmaster_ という接頭辞が付きます。

Direct（43）

すべての名前には yandex_direct_ という接頭辞が付きます。書き込みツールは、confirm: true を指定しない限り差分をプレビューし、プロジェクトごとの予算・入札変更制限を適用します（force: true で上書き可能）。プロジェクト設定で direct.sandbox: true を指定すると、Direct Sandbox に送信されます。書き込み結果には項目ごとの要約が含まれます。Direct は HTTP 成功レスポンス内で部分不一致を報告するため、partial_failure を確認してください。

プロジェクト管理（2）

yandex_projects_list, yandex_set_active_project — は マルチプロジェクト構成 を参照してください。

Metrika（22）

すべての名前には yandex_metrika_ という接頭辞が付きます。統計ツールは、広告レポート(ym:ad: メトリクス — Direct のコストと オン・サアイト行動を結合) 用の direct_client_logins と、その他任意のクエリパラメータ用の extra_params を受け付けます。

レポーテツールは Metrika Reporting API に基づいています。メトリクスとディメンションは ym:s:（ビジット）／ym:pv:（ページビュー）ネームスベースを使用します。例: metrics: "ym:s:visits,ym:s:users,ym:s:bouncerate"、dimensions: "ym:s:date,ym:s:lastTrafficSourc"。日付は YYYY-MM-DD または 相対キーワ－ド（today, yesterday, 7daysAgo）を対応しています。カウンター単位のツールでは、counter_id / ids が省か合わせた場合、プロジェクトの default_counter を既定に使用します。

プロジェクト構成

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

スクリプト

| Command         | Description                            |
| --------------- | -------------------------------------- |
| `npm run build` | TypeScript を `dist/` にコンパイルする |
| `npm run dev`   | `tsx` watch でソースから実行する        |
| `npm test`      | ユニットテストスイートを実行する (`tsx --test`) |
| `npm start`     | ビルド済みサーバーを実行する            |
| `npm run clean` | `dist/` を削除する                      |

## ライセンス

MIT © Minas Sarkisyan