yandex-metrica-mcp

yandex-metrica-mcp

Claude、Cursor、または任意の MCP クライアントから、Yandex Metrica の分析データに自然な言葉で質問できます。

Yandex Metrica（MCP）サーバーです。AI エージェントが、少数の柔軟な読み取り専用ツールを通じて、トラフィック、流入元、ランディングページ、コンバージョン、地域、デバイス、トレンドなどのウェブ分析データを照会できます。

設計上、読み取り専用です。パッケージにシークレットは保存されません。対話型ログインには組み込みの公開 OAuth クライアントを PKCE で使用し、サーバーは Yandex とのみ通信します。

ステータス：初期開発段階（v0.1、開発中）。汎用ツールです。SEO は多くのユースケースの一つであり、主な目的ではありません。

デモ

AI エージェントをカウンターに接続してトラフィックについて質問すると、サーバーが Yandex Metrica に問い合わせ、ダッシュボードを使わずに実際の読み取り専用データを返します。ここでは、ライブカウンターに対する「過去 7 日間のトラフィック流入元」という質問に、run_report ツールが回答しています。

クイックスタート

1. MCP クライアント（例：Claude Desktop）にサーバーを追加します。事前のトークンは不要です。手順 2 で対話形式のログインを行います。

{
    "mcpServers": {
        "yandex-metrica": {
            "command": "npx",
            "args": ["-y", "yandex-metrica-mcp"],
            "env": { "YANDEX_METRIKA_COUNTER_ID": "12345678" }
        }
    }
}

2. 一度だけログインします。コマンドは 1 つで、アプリ登録もシークレットの保存も不要です。

npx yandex-metrica-mcp auth

ブラウザーでアクセスを承認すれば完了です。ローカルリダイレクトを介してコードが自動的に戻されるため、コピー＆ペーストは不要です。ログインには認可コードと PKCE を使用するため、クライアントシークレットがマシンに保存されることはありません。トークンはキャッシュされ（モード 0600）、有効期間は約 1 年です。

3. トラフィック、流入元、コンバージョン、地域、デバイス、トレンドについてエージェントに質問します。プロンプトの例は例をご覧ください。

静的トークン（CI／非対話型）や独自の OAuth アプリを使いたい場合は、認証をご覧ください。

または Claude Code プラグインとしてインストール

このリポジトリはプラグインマーケットプレイスも兼ねているため、上記の設定の代わりに Claude Code のプラグインシステムからサーバーをインストールできます。

/plugin marketplace add BoxLab-Ltd/yandex-metrica-mcp
/plugin install yandex-metrica-mcp@boxlab

その後、npx yandex-metrica-mcp auth を実行して一度ログインします。

または Claude Desktop 拡張機能（.mcpb）としてインストール

JSON を使わずワンクリックでインストールするには、最新リリースから .mcpb をダウンロードし、Claude Desktop で開きます（または「設定」→「拡張機能」にドラッグします）。任意のデフォルトカウンター ID を尋ねられます。その後、チャットから login ツールでサインインするか、npx yandex-metrica-mcp auth を実行します。

このプロジェクトの理由

公式の Yandex Metrica MCP サーバーはなく、既存のコミュニティ製サーバーの多くは機能が薄く、メンテナンスされていないか、生データをそのままモデルのコンテキストに渡します。このサーバーは、柔軟なレポートツール、厳格なトークン／コンテキスト管理、デフォルトでの読み取り専用動作を備えた、適切に設計され、メンテナンスされたオープンな選択肢を目指しています。

機能（v0.1）

• run_report — Reporting API（/stat/v1/data）の柔軟なラッパーです。
• run_comparison — 2 つの期間を比較し、絶対値とパーセンテージの差分を返します。
• run_drilldown — ディメンションのツリーをたどって詳細を表示します。
• run_timeseries — トレンドを確認するため、指標を時系列（/bytime）に分割します。
• get_metadata — アカウントのカウンターと、一般的なディメンション／指標（および Logs API のフィールド）のカタログを取得します。モデルは実際の名称を使ってクエリを実行できます。
• describe_counter — include セレクターを使って、1 つのカウンターの設定（目標、セグメント、フィルター、演算、アクセス権限）を読み取ります。目標セクションには、run_report でコンバージョン指標を取得する際に必要な目標 ID が含まれています。
• logs_request / logs_status / logs_download / logs_clean — Logs API：サンプリングされていないセッション（visits）またはヒット（hits）の行データをエクスポートします。非同期のライフサイクル（リクエスト → ポーリング → ダウンロード → クリーンアップ）に対応しています。logs_download はデフォルトで上限付きのサンプルをインラインで返すか、エクスポート全体をファイルにストリーミングします。生データの行がモデルのコンテキストに出力されることはありません。
• login / submit_code — MCP クライアントから Yandex Metrica にサインインできます。ターミナルは不要です。login はブラウザーを開き、ローカルリダイレクト経由でコードを取得します。または URL を返し、貼り付けたコードを submit_code で受け取ります。
• 組み込みのコンテキスト制御：フィールド選択はデフォルトで有効で、デフォルトの行数制限は低く設定されており、サンプリングとクォータの情報はモデルに返されます。

今後の予定：Streamable HTTP トランスポート、書き込みツール（明示的なフラグを指定した場合のみ有効）。

要件

• Node.js >= 18
• metrika:read スコープを持つ Yandex Metrica の認証情報（Authentication を参照）。認証情報の所有者は、クエリ対象のカウンターにアクセスできる必要があります。

認証

推奨：対話型ログイン。 アプリの登録は不要です。サーバーには組み込みのパブリック OAuth クライアントが付属しています。次を一度実行します。

yandex-metrica-mcp auth     # or, in dev: bun run auth

ブラウザーで Yandex の同意ページが開き、承認すると、ループバックリダイレクト（http://127.0.0.1:53682）経由でコードが自動的に返されます。コピー＆ペーストは不要です。そのポートが使用中の場合は、コードを表示する方式に切り替わり、表示されたコードを貼り付けます（auth --oob でこの方式を強制するか、YANDEX_OAUTH_LOOPBACK_PORT でポートを変更できます）。トークンは ~/.config/yandex-metrica-mcp/token.json（モード 0600）にキャッシュされ、有効期間は約 1 年です。有効期限が切れたら auth を再実行してください。ログインには認可コード＋PKCE を使用するため、クライアントシークレットがどこにも保存されることはありません。キャッシュ済みのログインは YANDEX_METRIKA_TOKEN より優先されます。

MCP クライアントから（ターミナル不要）。 まだサインインしていませんか？サーバーはそのまま起動します。エージェントに login ツールを実行するよう依頼すると、同じブラウザーフローがプロセス内で実行されます（または URL が返され、submit_code でコードを受け取ります）。ターミナルから auth を実行できない Claude Desktop のような GUI クライアントに便利です。metrika:read スコープを持つアプリのトークンを https://oauth.yandex.ru で取得し、YANDEX_METRIKA_TOKEN として渡すこともできます。CI や非対話型の利用に便利です。

独自 OAuth アプリ（任意）。 組み込みアプリの代わりに独自のアプリを使用するには、YANDEX_OAUTH_CLIENT_ID を設定します。自動トークン更新も有効にするには、YANDEX_OAUTH_CLIENT_SECRET を追加します。

設定

クイックスタートでは、標準的な手順を説明しています。すべてのオプション（静的トークン、独自 OAuth アプリ、デフォルトのカウンター、リクエストの調整、言語）については、.env.example を参照してください。公開パッケージは Node で動作するため、npx／MCP クライアントですぐに使用できます。ローカル開発では Bun を使用します。

使用例

接続すると、エージェントは次のような質問に回答できます。

• 「counter 12345678 の先週の訪問数とユーザー数を、トラフィックソース別に教えてください」→ metrics: ["ym:s:visits","ym:s:users"]、dimensions: ["ym:s:lastsignTrafficSource"]を指定してrun_reportを実行します。
• 「今週と先週のオーガニック経由のコンバージョンを比較してください」→ run_comparison（サーバーはA、B、差分を返します）。
• 「訪問者が使用しているオペレーティングシステムを教えてください。Windowsのバージョンまで掘り下げてください」→ run_drilldownを実行し、続けてparentIdを指定して再度実行します。
• 「自分のカウンターを教えてください」→ get_metadata。
• 「このカウンターの目標を一覧表示してから、『Purchase』目標の先週のコンバージョン率を教えてください」→ describe_counter（include: ["goals"]）で目標IDを取得し、ym:s:goal<id>conversionRateを指定してrun_reportを実行します。
• 「オフライン分析用に、ランディングページとリファラーを含む先月の生セッションデータをエクスポートしてください」→ logs_request（source: "visits"）を実行し、logs_statusで状態を確認してから、logs_download（mode: "file"）を実行し、最後にlogs_cleanでクォータを解放します。

開発

このプロジェクトはBunを優先して使用します。

bun install
bun run dev        # run from source with hot reload
bun run typecheck  # tsc --noEmit
bun run lint       # eslint
bun test           # bun's test runner
bun run build      # emit dist/ with tsc (Node-compatible)

ライセンス

MIT © boxlab