Yandex Metrika MCP

yandex-metrika-mcp

Yandex Metrika API 用の MCP サーバーです。ウェブ解析データ（トラフィックの概要、オーディエンスの属性、トラフィックソース、人気のページ、検索フレーズ、カスタムレポート）にアクセスできます。

インストール

このパッケージは @stufently/yandex-metrika-mcp として公開されています。スコープなしの yandex-metrika-mcp は無関係なパブリッシャーのものです（ルート README の注記を参照）。 スコープにはまだ何も公開されていないため、ソースから実行してください。

git clone https://github.com/stufently/yandex-mcp.git
cd yandex-mcp && bun install
node packages/yandex-metrika-mcp/src/index.mjs

設定

MCP クライアントの設定に追加してください。

{
  "mcpServers": {
    "yandex-metrika": {
      "command": "node",
      "args": ["/path/to/yandex-mcp/packages/yandex-metrika-mcp/src/index.mjs"],
      "env": {
        "YANDEX_METRIKA_TOKEN": "your-oauth-token"
      }
    }
  }
}

環境変数

変数	必須	説明
YANDEX_METRIKA_TOKEN	はい	OAuth トークン。metrika:read で 10 個の読み取りツールを利用できます。create-counter と delete-counter には metrika:write も必要です
YANDEX_METRIKA_SCOPE	いいえ	認証フローが要求するスコープを上書きします。デフォルト：metrika:read metrika:write
YANDEX_CLIENT_ID	認証フローで必要	Yandex OAuth アプリのクライアント ID
YANDEX_CLIENT_SECRET	認証フローで必要	Yandex OAuth アプリのクライアントシークレット

認証

対話形式で OAuth トークンを取得するには：

node packages/yandex-metrika-mcp/src/index.mjs auth

Yandex OAuth 認証用にブラウザーが開き、トークンが返されます。これを YANDEX_METRIKA_TOKEN に設定してください。

スコープ

ヘルパーはデフォルトで metrika:read metrika:write を要求します。書き込みスコープは 単なる任意の飾りではありません。これがないと create-counter と delete-counter は HTTP 403 で拒否され、 拒否が発生するのはセットアップ時ではなく、カウンターを作成しようとしたときです。

読み取り専用のトークンにするには、要求するスコープを減らしてください。

YANDEX_METRIKA_SCOPE="metrika:read" node packages/yandex-metrika-mcp/src/index.mjs auth

その場合、書き込みツール 2 つは、不足しているスコープを明示したメッセージとともに 403 で失敗します。 どちらのツールの説明にもその旨が記載されているため、モデルは呼び出す前に「許可されていない」のか 「壊れている」のかを判別できます。

書き込み可能なトークンを使っても、無条件に削除できるわけではありません。delete-counter はスコープにかかわらず、 明示的に confirm: true を指定する必要があります。カウンターの削除を参照してください。

注：Metrika API では Authorization: OAuth {token} を使用します（Bearer ではありません）。

ツールリファレンス（12 個のツール）

管理（5 個）

ツール	説明	パラメーター
get-counters	すべての Metrika カウンター（サイト）を一覧表示します	--
get-counter	特定のカウンターの詳細を取得します	counter_id
get-goals	カウンターの目標を取得します	counter_id
create-counter	新しいカウンターを作成します（サイトを追加）。metrika:write が必要です	name, site, mirrors?, time_zone_name?, gdpr_agreement_accepted?
delete-counter	カウンターを削除します。元に戻せません。カウンターの削除を参照してください。confirm: true と metrika:write が必要です	counter_id, confirm

カウンターの削除

ここで唯一、元に戻せないツールである delete-counter は、呼び出しに confirm: true が含まれていないと実行されません。

{ "counter_id": 12345, "confirm": true }

この指定なしで呼び出すと、ツールはエラー結果を返し、Metrika API には何も送信しません。

Refused: `delete-counter` requires explicit confirmation.

Deleting counter 12345 is irreversible — the counter and every statistic it has collected are
gone for good. Yandex cannot restore them, and creating a new counter for the same site does
not bring the history back.

Nothing was sent to the Metrika API — no counter was touched.

To go ahead, call `delete-counter` again with counter_id 12345 and `confirm: true`. To check
which site this counter belongs to first, call `get-counter`.

confirm は意図的に JSON スキーマで省略可能になっています。確認が指定されていない場合に、 モデルが対処できないスキーマ検証エラーではなく、その説明が返される必要があるためです。文字どおりの true だけが有効です。"true"、1、"yes" は拒否されます。プロトコルを推測しただけでは、 何かを削除する決定にはならないからです。また、このツールには MCP アノテーションで destructiveHint: true が設定されているため、ツールのリスクを表示するクライアントは呼び出し前にその情報を示せます。

このパラメーターが存在する理由：デフォルトの OAuth スコープに metrika:write が含まれるようになる前は、 読み取り専用トークンが返す 403 によって、誤って delete-counter を実行することは阻止されていました。 （初回からセットアップが機能するよう）この 403 を解消したことで、唯一の実質的な歯止めがなくなりました。 説明に「元に戻せません」と書くのは、モデルが注意深く読むことへの期待であって、保護策ではありません。

レポート（6）

ツール	説明	パラメーター
get-traffic-summary	訪問数、ユーザー数、ページビュー数、直帰率、平均滞在時間	counter_id、date_from?、date_to?
get-traffic-sources	トラフィックの流入元別内訳	counter_id、date_from?、date_to?、limit?（デフォルト：10）
get-geography	国・都市別のトラフィック内訳	counter_id、date_from?、date_to?、limit?（デフォルト：10）
get-devices	デバイス、ブラウザー、OS 別のトラフィック内訳	counter_id、group_by?（device/browser/os、デフォルト：device）、date_from?、date_to?、limit?（デフォルト：10）
get-popular-pages	最も閲覧されたページ	counter_id、date_from?、date_to?、limit?（デフォルト：10）
get-search-phrases	トラフィックをもたらす検索フレーズの上位	counter_id、date_from?、date_to?、limit?（デフォルト：20）

カスタム（1）

ツール	説明	パラメーター
get-report	任意の指標とディメンションを指定してカスタムレポートを実行します	counter_id、metrics、dimensions?、date_from?、date_to?、filters?、sort?、limit?（デフォルト：10）

get-report のパラメーター

get-report ツールでは、Metrika Stat API にフルアクセスできます。

パラメーター	型	必須	説明
counter_id	number	はい	カウンター ID
metrics	string	はい	カンマ区切りの指標（例：ym:s:visits,ym:s:users）
dimensions	string	いいえ	カンマ区切りのディメンション（例：ym:s:trafficSource）
date_from	string	いいえ	開始日 YYYY-MM-DD（デフォルト：30 日前）
date_to	string	いいえ	終了日 YYYY-MM-DD（デフォルト：今日）
filters	string	いいえ	フィルター式（例：ym:s:trafficSource=='organic'）
sort	string	いいえ	並べ替えフィールド。降順にするには先頭に - を付けます
limit	number	いいえ	最大結果数（デフォルト：10）

デフォルトの日付範囲

date_from と date_to を指定しない場合、すべてのレポートツールでは過去 30 日間がデフォルトになります。

データのサンプリング

Metrika Stat API は、大規模なデータセットに対してサンプリングされたデータを返す場合があります。サンプリングが適用されると、数値が概算であることを示す注記がレスポンスに含まれます。

ライセンス

MIT