@rezlazy/yandex-metrika-mcp

Yandex Metrika Reports API（/stat/v1/*）および Management API（/management/v1/*）用のMCPサーバーです。

68ツールを公開しています：レポート用6ツールと管理用62ツール（カウンター、ゴール、フィルター、アクセス権限、セグメント、ラベルなど）。

要件

• Node.js 20+

• metrika:read（レポート）および/または metrika:write（作成・更新・削除）権限を持つOAuthトークン

Related MCP server: Google Analytics MCP Server

OAuthトークンの取得

1. Yandex OAuthアプリを作成 — For API access or debugging を選択します。

2. 権限 metrika:read（レポート）と metrika:write（管理変更）を追加します。

3. アプリの Client ID をコピーします。

4. ブラウザで開きます：

   https://oauth.yandex.ru/authorize?response_type=token&client_id=<CLIENT_ID>

5. リダイレクトURL（access_token=...）からトークンをコピーします。

Yandex Metrika認証ドキュメント を参照してください。

Cursorの設定

.cursor/mcp.json またはCursor MCP設定に追加します：

{
  "mcpServers": {
    "yandex-metrika": {
      "command": "npx",
      "args": ["-y", "@rezlazy/yandex-metrika-mcp"],
      "env": {
        "METRIKA_TOKEN": "<your-oauth-token>"
      }
    }
  }
}

ローカル開発用（このリポジトリの .cursor/mcp.json）：

{
  "mcpServers": {
    "yandex-metrika": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

プロジェクトルートに .env を作成します：

METRIKA_TOKEN=your_oauth_token

MCPサーバーの実行

サーバーは stdio（標準入力/標準出力）を使用し、HTTPではありません。Webサーバーのように起動するのではなく、MCPクライアント（例：Cursor）が子プロセスとして起動します。

要件： Node.js 20+、METRIKA_TOKEN、およびビルド済みの dist/index.js（ローカル開発用）。

Cursorでの実行（推奨）

1. .cursor/mcp.json またはCursor MCP設定でMCPを設定します（上記の例を参照）。

2. Settings → MCP → Refresh を実行するか、Cursorを再起動します。

Cursorはツール使用時に node dist/index.js（ローカル）または npx @rezlazy/yandex-metrika-mcp（npm）を自動的に実行します。失敗した場合は Output → MCP Logs を確認してください。

GitHubから（npm公開なし）

{
  "mcpServers": {
    "yandex-metrika": {
      "command": "npx",
      "args": ["-y", "github:Rezlazy/yandex-metrika-mcp"],
      "env": {
        "METRIKA_TOKEN": "<your-oauth-token>"
      }
    }
  }
}

gitインストールの場合、dist/ がリポジトリに存在するか、インストール時にビルドされる必要があります（例：prepare スクリプト経由）。

手動実行（デバッグのみ）

npm run build
export METRIKA_TOKEN=your_oauth_token
node dist/index.js

プロセスは標準入力でJSON-RPCを静かに待機します — これは正常です。METRIKA_TOKEN がない場合はエラーで終了します。

マルチルートワークスペース（*.code-workspace）

mcp.code-workspace（1つのウィンドウに複数のフォルダ）を開くと、CursorはSettings → MCPで .cursor/mcp.json のプロジェクトMCPサーバーを 表示しない 場合があります。これは既知のCursorの制限です。

回避策：

1. このリポジトリを直接開く： File → Open Folder → yandex-metrika-mcp（.code-workspace ファイルではなく）。

2. またはグローバル設定に追加 ~/.cursor/mcp.json（マルチルートで動作）：

"yandex-metrika": {
  "type": "stdio",
  "command": "node",
  "args": ["/absolute/path/to/yandex-metrika-mcp/dist/index.js"],
  "envFile": "/absolute/path/to/yandex-metrika-mcp/.env"
}

設定変更後：設定でMCPを Refresh するか、Cursorを再起動します。ログを確認：Outputパネル → MCP Logs。

環境変数

ツール

レポート（stat_*）— 6ツール

管理（mgmt_*）— 62ツール

Management API をカバー：カウンター、ゴール、フィルター、操作、アクセス権限、アクセスフィルター、セグメント、チャート注釈、ラベル、アカウント、委任、クライアント、クラウドエクスポート。

一般的な管理ツール：

POST/PUTメソッドでは、body パラメータにJSONを渡します（APIフォーマット を参照）。カウンター作成の例：

{
  "body": {
    "counter": {
      "name": "My site",
      "site": "example.com"
    }
  }
}

レポートパラメータ

• ids — カウンターID（カンマ区切り）

• metrics — 例：ym:s:visits、ym:s:users、ym:s:pageviews

• dimensions — 例：ym:s:trafficSource、ym:s:operatingSystem

• date1 / date2 — 期間（7daysAgo、today、または YYYY-MM-DD）

• filters — セグメンテーション式

• preset — レポートプリセット

• format — json（デフォルト）または csv

メトリクスとディメンションの完全なリスト：attrandmetr。

例：トラフィックソース別訪問数

ツール：stat_data

{
  "ids": "44147844",
  "metrics": "ym:s:visits,ym:s:users",
  "dimensions": "ym:s:trafficSource",
  "date1": "30daysAgo",
  "date2": "today",
  "sort": "-ym:s:visits",
  "limit": "10"
}

例：日次訪問トレンド

ツール：stat_bytime

{
  "ids": "44147844",
  "metrics": "ym:s:visits",
  "date1": "30daysAgo",
  "date2": "today",
  "group": "day"
}

開発

npm install
npm run typecheck
npm test
npm run build

npmへの公開

公開は、GitHub Release が公開されたときにGitHub Actionsによって自動化されます。

初回設定：

1. npmjs.com でnpm組織/スコープ @rezlazy を作成します。

2. npm Automation トークンを生成します。

3. GitHubリポジトリに NPM_TOKEN シークレットを追加します。

4. タグ v0.1.0 でリリースを作成します — ワークフローが @rezlazy/yandex-metrika-mcp を公開します。

ライセンス

MIT