Yandex Metrica MCP

yandex-metrica-mcp

Yandex Metrica Reporting API、Logs API、カウンター管理のための MCP サーバーです。Claude Code と Codex CLI での使用を想定しています。13 個のツールのうち 8 個は読み取り専用で、5 個は Metrica アカウントを変更します。カウンターの作成と削除、および Logs API エクスポートの作成、キャンセル、クリーンアップを行います。各ツールの種別は MCP アノテーション（readOnlyHint、destructiveHint）で示されます。

stdio を介してローカルで実行されます。ウェブサーバー、永続ストレージ、バックグラウンドデーモンはありません。

---

このプロジェクトの目的

Yandex Metrica には、異なる目的で使用される 2 種類の API があります。

• Reporting API（/stat/v1/data） — 集計済みのサンプリング統計です。レポートの作成、トラフィックソースの照会、行動指標や目標コンバージョンなどの取得に使用します。
• Logs API（/management/v1/counter/{id}/logrequests） — 集計されていない生のイベントエクスポートです。カスタム分析パイプライン用に、セッションやヒットの行単位のデータが必要な場合に使用します。

この MCP サーバーは両方の API を名前付きツールとして公開し、LLM から直接呼び出せるようにします。

---

機能

• カウンター管理、目標、レポート、Logs API の全ライフサイクルを網羅する 13 個の MCP ツール
• 環境変数のみで認証（対話型 OAuth は不要）
• 変換を最小限に抑え、レスポンスは Yandex API の形式に近いまま保持
• 安全なダウンロード動作：ログのパートはデフォルトで 50KB のプレビューとメタデータを返します
• 厳格な TypeScript、zod による検証、明確なエラーメッセージ
• マルチステージ Docker イメージ（node:24-alpine）
• 単体テストとモック統合テスト、ライブテスト用の基盤
• GitHub Actions の CI および Docker ワークフロー

---

対応している MCP ツール

カウンター管理

ツール	説明
yandex_metrica_list_counters	アクセス可能なカウンター（タグ）の一覧を取得
yandex_metrica_get_counter	ID を指定してカウンターの詳細を取得
yandex_metrica_list_goals	カウンターの目標一覧を取得
yandex_metrica_create_counter	新しいカウンターを作成（サイトを追加）
yandex_metrica_delete_counter	カウンターを完全に削除

Reporting API（集計済み）

ツール	説明
yandex_metrica_get_report	Reporting API クエリを実行

期間を比較するには、yandex_metrica_get_report に date1_b／date2_b を渡します。このツールは自動的に /stat/v1/data/comparison に振り分けます。date1／date2 はセグメント A に、date1_b／date2_b はセグメント B になります。各結果行は metrics: { a, b } を返します。

Logs API（生データのエクスポート）

ツール	説明
yandex_metrica_evaluate_logs_request	エクスポートが可能か確認
yandex_metrica_create_logs_request	非同期エクスポートリクエストを作成
yandex_metrica_list_logs_requests	カウンターの全リクエストを一覧表示
yandex_metrica_get_logs_request	リクエストのステータスを確認
yandex_metrica_download_logs_part	処理済みパートをダウンロード（TSV）
yandex_metrica_cancel_logs_request	保留中のリクエストをキャンセル
yandex_metrica_clean_logs_request	クォータを解放するため処理済みファイルをクリーンアップ

---

Logs API のワークフロー

evaluate → create → [poll get until status=processed] → download parts → clean

Logs API は非同期です。リクエストを作成した後、status = "processed" になるまで yandex_metrica_get_logs_request をポーリングし、その後 log_request.parts に記載された各パートを（part_number で）ダウンロードします。

---

ダウンロードの動作

生のログパートは数百 MB に達することがあります。デフォルトでは、yandex_metrica_download_logs_part は次の内容を返します。

{
  "mode": "preview",
  "truncated": true,
  "original_byte_size": 52428800,
  "preview_byte_size": 49980,
  "content": "ym:s:visitID\tym:s:date\t...\n..."
}

全内容を取得するには mode: "full" を設定します。ただし、小さなパートの場合にのみ使用してください。

---

要件

• Node.js 24+
• metrika:read スコープを持つ Yandex OAuth トークン

YANDEX_METRICA_TOKEN の取得方法

1. https://oauth.yandex.com/ にアクセスします → アプリを作成
2. 任意の名前を入力し、API アクセス用を選択します
3. アクセス権で metrika:read を有効にします
4. アプリを作成をクリックし、ClientIDをコピーします
5. ブラウザーで開きます（<ClientID> をご自身のものに置き換えてください）：

   https://oauth.yandex.com/authorize?response_type=token&client_id=<ClientID>
   

6. 認証し、URL フラグメント（#access_token=...）から access_token をコピーします

YANDEX_METRICA_COUNTER_ID の取得方法

カウンター ID は、Yandex Metrica タグ（счётчик）の数値 ID です。

• https://metrika.yandex.ru を開きます。カウンター ID は各タグの横に表示されます
• URL を確認します：metrika.yandex.ru/dashboard?id=**12345678**
• または、ツール自体を使用します：yandex_metrica_list_counters を呼び出すと、すべてのカウンターとその ID が返されます

YANDEX_METRICA_COUNTER_ID が必要なのはライブテスト（npm run test:live）のみで、通常のサーバー動作には不要です。

---

インストール

docker run -i --rm -e YANDEX_METRICA_TOKEN ghcr.io/stufently/yandex-metrica-mcp:latest

現在利用できる方法は Docker です。 クローンも Node.js も必要ありません。以下の各 MCP クライアントは、すべて同じコマンドでサーバーを起動します。

値を指定せずに -e YANDEX_METRICA_TOKEN を指定すると、クライアントの環境からコンテナに変数が渡されます。そのため、トークンはクライアントの env ブロック内に保持され、docker コマンドラインや ps の出力には表示されません。クライアントは初回起動時にイメージを取得します。あらかじめ docker pull ghcr.io/stufently/yandex-metrica-mcp:latest を実行しておくと、初回起動が速くなります。

トークンやネットワークを使わずにスモークテストを実行できます。サーバーが initialize に応答し、13 個のツールを一覧表示すれば成功です。イメージにはプレースホルダーの YANDEX_METRICA_TOKEN が含まれているため、イントロスペクション用に起動できます。このトークンを使ったツール呼び出しは Yandex に接続せず、「YANDEX_METRICA_TOKEN is not set」エラーを返します。

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | docker run -i --rm --network none ghcr.io/stufently/yandex-metrica-mcp:latest

GHCR のイメージタグ：latest と main（main へのプッシュごと）、sha-<short>、およびバージョンタグの X.Y.Z / X.Y / X です。再現可能なセットアップには、バージョンタグ（:0.2.3）を固定してください。

npm（未公開）

パッケージはスコープ付きです。スコープなしの名前（yandex-metrica-mcp と、以前のプロジェクト名である mcp-yandex-metrica）は、どちらも npm 上の無関係なプロジェクトが使用しているため、@stufently/yandex-metrica-mcp（コマンドは yandex-metrica-mcp）として公開されます。npm の初回リリースはまだ行われていないため、現時点では npx -y @stufently/yandex-metrica-mcp は動作しません。Docker を使用してください。

ソースから

git clone https://github.com/stufently/yandex-metrica-mcp.git
cd yandex-metrica-mcp
npm install && npm run build

クライアントの設定については、ローカルビルドからの実行を参照してください。

---

設定

.env.example を .env にコピーし、トークンを設定します。

cp .env.example .env

変数	必須	デフォルト	説明
YANDEX_METRICA_TOKEN	はい	—	metrika:read 権限を持つ OAuth トークン
YANDEX_METRICA_TIMEOUT_MS	いいえ	30000	リクエストのタイムアウト（ミリ秒）
LOG_LEVEL	いいえ	info	ログレベル：debug、info、warn、error、silent
YANDEX_METRICA_USER_AGENT	いいえ	yandex-metrica-mcp/0.2.3	カスタム User-Agent
YANDEX_METRICA_BASE_URL	いいえ	https://api-metrika.yandex.net	API ベース URL（テストのみ）

---

ローカル開発

# Development with hot reload
YANDEX_METRICA_TOKEN=your_token npm run dev

# Build
npm run build

# Run production build
YANDEX_METRICA_TOKEN=your_token npm start

# Lint
npm run lint

# Type check
npm run typecheck

# Tests (unit + mock integration, no live API calls)
npm test

# Live tests (requires real token and counter ID)
LIVE_TESTS=1 YANDEX_METRICA_TOKEN=your_token YANDEX_METRICA_COUNTER_ID=12345678 npm run test:live

# Format
npm run format

---

Docker

# Use pre-built image from GHCR (updated on every push to main)
docker run -i --rm \
  -e YANDEX_METRICA_TOKEN=your_token \
  ghcr.io/stufently/yandex-metrica-mcp:latest

# Or build locally
docker build -t yandex-metrica-mcp:local .
docker run -i --rm \
  -e YANDEX_METRICA_TOKEN=your_token \
  yandex-metrica-mcp:local

Docker Compose

# Create .env with your token first
cp .env.example .env

# Run
docker-compose run --rm yandex-metrica-mcp

---

検証済みのクライアントとプラットフォーム

実際に実行したものだけを検証済みとして記載しています。 クライアントの設定に記載されているその他の設定は、エンドツーエンドで誰も確認していない、ドキュメント上の設定です。

クライアント／ランタイム	OS	実行方法	ステータス	根拠
Claude Code 2.1	Ubuntu 26.04 LTS, x86_64	このリポジトリからローカルでビルドした Docker イメージ、stdio	検証済み	メンテナーのホストで日常的に使用（カウンター、レポート、目標）
Node.js 24	Ubuntu (ubuntu-latest)	npm ci、lint、typecheck、ユニットテスト＋モック統合テスト、ビルド	CI で検証済み	ci.yml
Docker イメージ	Ubuntu (ubuntu-latest)	すべてのプルリクエストと main へのプッシュ時にイメージをビルド	CI でビルド済み、そこで起動はしていません	docker.yml
Claude Desktop (.mcpb)	macOS, Windows	デスクトップ拡張機能	未検証	バンドルは CI でビルドされますが、実際の Desktop には一度もインストールされていません
Cursor、Windsurf、Codex CLI、Zed	任意	以下の設定	未検証	ドキュメントに記載されているのみ
macOS、Windows	—	任意のクライアント	未検証	これらのシステムには CI ランナーがありません

クライアントの設定

以下の設定はすべてコピー＆ペーストして使用でき、インストールに記載された Docker コマンドを使います。your_oauth_token_here を Yandex OAuth トークンに置き換え、それ以外は変更しないでください。

Claude Code

プロジェクトファイル：プロジェクトのルートにある .mcp.json。

claude mcp add yandex-metrica \
  -e YANDEX_METRICA_TOKEN=your_oauth_token_here \
  -- docker run -i --rm -e YANDEX_METRICA_TOKEN ghcr.io/stufently/yandex-metrica-mcp:latest

すべてのプロジェクトで使用できるようにするには --scope user を追加し、.mcp.json に書き込むには --scope project を追加します。claude mcp list ／ claude mcp get yandex-metrica で確認してください。

.mcp.json に JSON として記述する場合も、同じサーバーを使用します。

{
  "mcpServers": {
    "yandex-metrica": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "YANDEX_METRICA_TOKEN",
        "ghcr.io/stufently/yandex-metrica-mcp:latest"
      ],
      "env": {
        "YANDEX_METRICA_TOKEN": "your_oauth_token_here"
      }
    }
  }
}

Claude Desktop

設定ファイル claude_desktop_config.json の保存先：macOS は ~/Library/Application Support/Claude/、Windows は %APPDATA%\Claude\、Linux は ~/.config/Claude/ です。保存後、アプリを再起動してください。

{
  "mcpServers": {
    "yandex-metrica": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "YANDEX_METRICA_TOKEN",
        "ghcr.io/stufently/yandex-metrica-mcp:latest"
      ],
      "env": {
        "YANDEX_METRICA_TOKEN": "your_oauth_token_here"
      }
    }
  }
}

Claude Desktop では、.mcpb ファイルからこのサーバーをワンクリックでインストールすることもできます。v0.2.0 までのリリースにはまだ含まれていません。次のタグ付きリリースから、バンドルが https://github.com/stufently/yandex-metrica-mcp/releases/latest に添付されます。それまでは、bash scripts/build-mcpb.sh（Docker が必要です）でローカルにビルドし、dist-mcpb/yandex-metrica-mcp-<version>.mcpb を開いてください。

リリースには、各 .mcpb バンドルの SHA256 チェックサムを記載した checksums.txt が含まれています。バンドルと一緒にダウンロードし、インストール前に検証してください。

sha256sum -c --ignore-missing checksums.txt   # run next to the downloaded .mcpb

次のタグ以降のリリースには、各 .mcpb の GitHub ビルド来歴証明も含まれ、リリースワークフローで署名されます。バンドルがこのリポジトリのワークフローでビルドされ、その後差し替えられていないことを確認してください（GitHub CLI が必要です）。

gh attestation verify <bundle>.mcpb --repo stufently/yandex-metrica-mcp

Cursor

インストール後、~/.cursor/mcp.json の your_oauth_token_here をご自身のトークンに置き換えてください。または、以下のブロックを手動で追加してください。

すべてのプロジェクトに適用する場合は ~/.cursor/mcp.json、1つのプロジェクトに適用する場合は .cursor/mcp.json を使用します。

{
  "mcpServers": {
    "yandex-metrica": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "YANDEX_METRICA_TOKEN",
        "ghcr.io/stufently/yandex-metrica-mcp:latest"
      ],
      "env": {
        "YANDEX_METRICA_TOKEN": "your_oauth_token_here"
      }
    }
  }
}

Windsurf

mcp_config.json ファイルを使用します。macOS と Linux の場合： ~/.config/devin/mcp_config.json（または $XDG_CONFIG_HOME/devin/mcp_config.json）。Windows の場合： %APPDATA%\devin\mcp_config.json。以前のビルドでは ~/.codeium/windsurf/mcp_config.json を使用していました。

{
  "mcpServers": {
    "yandex-metrica": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "YANDEX_METRICA_TOKEN",
        "ghcr.io/stufently/yandex-metrica-mcp:latest"
      ],
      "env": {
        "YANDEX_METRICA_TOKEN": "your_oauth_token_here"
      }
    }
  }
}

Codex CLI

codex mcp add yandex-metrica \
  --env YANDEX_METRICA_TOKEN=your_oauth_token_here \
  -- docker run -i --rm -e YANDEX_METRICA_TOKEN ghcr.io/stufently/yandex-metrica-mcp:latest

または、~/.codex/config.toml に手動で設定します（Codex CLI、IDE 拡張機能、デスクトップアプリで共有されます）。

[mcp_servers.yandex-metrica]
command = "docker"
args = ["run", "-i", "--rm", "-e", "YANDEX_METRICA_TOKEN", "ghcr.io/stufently/yandex-metrica-mcp:latest"]
env = { YANDEX_METRICA_TOKEN = "your_oauth_token_here" }

Zed

Zed の settings.json（zed: open settings file）で、context_servers の下に設定します。

{
  "context_servers": {
    "yandex-metrica": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "YANDEX_METRICA_TOKEN",
        "ghcr.io/stufently/yandex-metrica-mcp:latest"
      ],
      "env": {
        "YANDEX_METRICA_TOKEN": "your_oauth_token_here"
      }
    }
  }
}

Docker ではなくローカルビルドから実行する

上記のどのクライアントでも動作します。command／args を次の内容に置き換えてください。

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

Claude Code では、CLI から同じ設定を行えます。

claude mcp add yandex-metrica \
  -e YANDEX_METRICA_TOKEN=your_oauth_token_here \
  -- node /absolute/path/to/yandex-metrica-mcp/dist/index.js

---

プロンプトの例

• 先週、サイトの訪問数が減ったのはなぜですか？
• 先月、最も多くの訪問をもたらしたトラフィックソースはどれですか？
• メインのカウンターにはどのような目標が設定されていますか？
• 今月の訪問数を、昨年の同じ月と比較してください。
• 1月の最初の週の生の訪問データをエクスポートして、プレビューを表示してください。

よく使うプロンプト

サーバーを登録したら、自然な言葉で質問してください。ツールはクライアントが選択します。

アクセスできる項目を一覧表示する → yandex_metrica_list_counters

List all my Yandex Metrica counters with their IDs and site names.

期間を指定してトラフィックレポートを取得する → yandex_metrica_get_report

Show visits, users and bounce rate for counter 12345678 for the last 7 days,
broken down by date.

トラフィックソースの上位を取得する → yandex_metrica_get_report

What were the top 10 traffic sources for counter 12345678 last month,
by visits and conversion rate?

2つの期間を比較する → date1_b／date2_b を指定して yandex_metrica_get_report

Compare visits and average session duration for counter 12345678
between this month and the same month last year.

目標コンバージョンを取得する → yandex_metrica_list_goals + yandex_metrica_get_report

List the goals configured on counter 12345678, then show conversions
for each of them over the last 30 days.

生のイベントデータをエクスポートする → Logs API の一連の操作（evaluate → create → get → download_part → clean）

Export raw visits for counter 12345678 from 2024-01-01 to 2024-01-07 with fields
visitID, date, clientID, startURL, trafficSource. Poll until it is ready,
then show me a preview of the first part.

---

アーキテクチャ

src/
  index.ts              Entry point, loads config, connects stdio transport
  config/env.ts         Zod-based environment config validation
  server/
    createServer.ts     Creates MCP Server instance
    registerTools.ts    Registers all tools with the server
  tools/                One file per MCP tool
  client/
    http.ts             Fetch-based HTTP client with auth, timeout, error handling
    management.ts       Counters and goals endpoints
    reporting.ts        Reporting API (/stat/v1/data)
    logs.ts             Logs API lifecycle endpoints
  schemas/              Zod schemas for tool input validation
  errors/               YandexApiError + error mapping
  types/api.ts          TypeScript types for Yandex API responses
  utils/
    arrays.ts           Array → comma-separated conversion
    text.ts             Text preview/truncation for large downloads

---

制限事項

• 読み取り専用ではありません — 読み取りツールは8個、書き込みツールは5個です。カウンターの作成／削除と、Logs API のエクスポート処理（作成、キャンセル、クリーンアップ）が含まれます
• 比較レポート用のツールはありません — date1_b／date2_b パラメーターを指定して yandex_metrica_get_report を使用してください
• v1 ではドリルダウン／ピボット／時間別のツールはありません — v0.2 で対応予定です
• キャッシュはありません — ツールを呼び出すたびに Yandex API にアクセスします
• 大きなログパーツ — mode: "full" は慎重に使用してください。デフォルトでは50KBのプレビューが返されます
• 指数バックオフによる再試行が組み込まれています（3回、ステータスコード 429/500/502/503/504）

---

テスト

# Unit + mock integration (CI-safe, no real API calls)
npm test

# Live tests (hit real Yandex API)
LIVE_TESTS=1 \
YANDEX_METRICA_TOKEN=your_token \
YANDEX_METRICA_COUNTER_ID=12345678 \
npm run test:live

---

CI / Docker イメージ

GitHub Actions のワークフローは .github/workflows/ にあります。

• ci.yml — プッシュ／PR のたびに、lint、型チェック、テスト、ビルドを実行します
• docker.yml — Docker イメージをビルドします。main へのプッシュ時とバージョンタグのプッシュ時に GHCR へプッシュします。 vX.Y.Z タグでは、server.json も 公式 MCP Registry に io.github.stufently/yandex-metrica-mcp として公開します（GitHub OIDC を使用し、シークレットの保存は不要です）
• mcpb.yml — vX.Y.Z タグでは、.mcpb Desktop 拡張機能をビルドし、該当する GitHub Release に添付します。GHCR、npm、PyPI、MCP Registry には公開しません。

docker.yml が生成するイメージタグ：

タグ	タイミング
latest	main へのプッシュのたび
main	main へのプッシュのたび
sha-<short>	main へのプッシュおよび各バージョンタグ
X.Y.Z、X.Y、X	vX.Y.Z git タグのプッシュ時

REGISTRY と IMAGE_NAME のデフォルト値は、それぞれ ghcr.io と ${{ github.repository }} です。

---

セキュリティ

• トークンは環境変数を介してのみ渡されます。ハードコードされることはありません
• トークンがログに出力されることはありません
• カウンターの作成・削除には metrika:write スコープが必要です。それ以外のツールはすべて読み取り専用アクセスを使用します
• Docker イメージは root 以外のユーザー（node ユーザー）で実行されます

---

ライセンス

MIT — LICENSE を参照してください