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 在本地运行。没有 Web 服务器、持久化存储或后台守护进程。

---

为什么要开发这个项目

Yandex Metrica 有两个用途各异的 API：

• Reporting API（/stat/v1/data）——汇总后的抽样统计数据。可用于生成报告、查询流量来源、行为指标、目标转化等。
• Logs API（/management/v1/counter/{id}/logrequests）——原始、未汇总的事件导出。需要在自定义分析管道中使用会话或点击级数据行时，请使用此 API。

此 MCP 服务将这两个 API 封装为可供大模型直接调用的命名工具。

---

功能

• 提供 13 个 MCP 工具，涵盖计数器管理、目标、报告和完整的 Logs API 生命周期
• 仅通过环境变量进行身份验证（无需交互式 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 是异步的。创建请求后，轮询 yandex_metrica_get_logs_request，直到 status = "processed"，然后下载 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_METRICA_TOKEN”错误， 而不会连接 Yandex：

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

客户端配置请参阅从本地构建运行（而非使用 Docker）。

---

配置

将 .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

---

已验证的客户端和平台

这里只列出实际运行过的项目。客户端配置中的其他配置都是有文档记录、但未经端到端检查的配置。

客户端 / 运行时	操作系统	运行方式	状态	证据
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 可让它在每个项目中都可用；添加 --scope project 则会写入 .mcp.json。使用 claude mcp list / claude mcp get yandex-metrica 检查。

同一服务的 JSON 配置如下，位于 .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"
      }
    }
  }
}

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。

发布版本包含 checksums.txt，其中列出了每个 .mcpb 安装包的 SHA256 校验和。请将其与安装包一并下载，并在安装前进行验证：

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，单个项目使用 .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?

比较两个时间段 → 使用 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 桌面扩展并将其附加到对应的 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