@rezlazy/yandex-metrika-mcp

用于 Yandex Metrika 报表 API（/stat/v1/*）和 管理 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（用于 API 访问或调试）。

2. 添加权限 metrika:read（报表）和 metrika:write（管理更改）。

3. 复制应用的 Client ID（客户端 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. 设置 → MCP → 刷新，或重启 Cursor。

Cursor 会在使用工具时自动运行 node dist/index.js（本地）或 npx @rezlazy/yandex-metrika-mcp（npm）。如果出现问题，请检查 输出 → MCP 日志。

从 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（一个窗口中的多个文件夹），Cursor 可能不会在 设置 → MCP 中显示来自 .cursor/mcp.json 的项目 MCP 服务器。这是 已知的 Cursor 限制。

解决方法：

1. 直接打开此仓库： 文件 → 打开文件夹 → 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 或重启 Cursor。检查日志：输出面板 → MCP 日志。

环境变量

工具

报表（stat_*）— 6 个工具

管理（mgmt_*）— 62 个工具

涵盖 管理 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 Actions 在发布 GitHub Release 时自动完成。

一次性设置：

1. 在 npmjs.com 上创建 npm 组织/范围 @rezlazy。

2. 生成 npm Automation（自动化）令牌。

3. 将 NPM_TOKEN 密钥添加到 GitHub 仓库。

4. 使用标签 v0.1.0 创建 Release — 工作流将发布 @rezlazy/yandex-metrika-mcp。

许可证

MIT