yandex-metrica-mcp

yandex-metrica-mcp

用日常语言查询 Yandex Metrica 分析数据——通过 Claude、Cursor 或任意 MCP 客户端。

一个用于 Yandex Metrica 的 Model Context Protocol（MCP）服务。它能让 AI Agent 通过一组灵活的只读工具查询网站分析数据，包括流量、来源、着陆页、转化、地域、设备和趋势。

从设计上就是只读的，程序包中不存储密钥：交互式登录使用内置的公开 OAuth 客户端和 PKCE，服务只与 Yandex 通信。

状态：早期开发阶段（v0.1，仍在开发中）。用途广泛：SEO 只是众多应用场景之一，并非重点。

演示

将 AI Agent 接入你的计数器，询问流量情况——服务会查询 Yandex Metrica 并返回真实的只读数据，无需查看仪表板。此处，run_report 工具根据一个正在运行的计数器回答了“过去 7 天的流量来源”问题：

快速开始

1. 将服务添加到 MCP 客户端（例如 Claude Desktop）——无需预先提供令牌；在第 2 步中交互式登录即可：

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

2. 登录一次——只需一条命令，无需注册应用，也不会存储密钥：

npx yandex-metrica-mcp auth

在浏览器中批准访问即可完成——授权码会通过本地重定向自动返回，无需复制粘贴。登录使用授权码 + PKCE，因此客户端密钥绝不会接触你的设备；令牌会被缓存（权限模式为 0600），有效期约为 1 年。

3. 向 Agent 询问流量、来源、转化、地域、设备或趋势——提示词示例请参阅示例。

想使用静态令牌（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 — 比较两个时间段，并显示绝对值和百分比的变化。
• run_drilldown — 沿维度树逐级深入分析。
• run_timeseries — 按时间序列拆分指标（/bytime），用于分析趋势。
• get_metadata — 查找账户上的计数器，以及常用维度/指标（和 Logs API 字段）目录，让模型使用真实名称进行查询。
• describe_counter — 通过 include 选择器读取单个计数器的配置（目标、细分、过滤器、操作、访问授权）。目标部分提供 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 凭据（参见 身份验证）。凭据所属者必须有权访问你要查询的计数器。

身份验证

推荐：交互式登录。 无需注册应用——服务内置了公共 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 客户端登录（无需终端）。 尚未登录？服务仍会启动——让你的 Agent 运行 login 工具，即可在进程内完成相同的浏览器登录流程（也可以返回 URL，并通过 submit_code 接收代码）。对于 Claude Desktop 等没有终端可运行 auth 的图形界面客户端，这会很方便。也可以在 https://oauth.yandex.ru 为应用获取具有 metrika:read 作用域的令牌，并将其设为 YANDEX_METRIKA_TOKEN——适用于 CI 或非交互式使用。

使用自己的 OAuth 应用（可选）。 若要使用自己的应用而非内置应用，请设置 YANDEX_OAUTH_CLIENT_ID；同时设置 YANDEX_OAUTH_CLIENT_SECRET 可启用自动令牌刷新。

配置

快速入门介绍了最简单的使用流程。所有选项——静态令牌、自有 OAuth 应用、默认计数器、请求调优、语言——请参见 .env.example。已发布的软件包运行于 Node（因此 npx/MCP 客户端开箱即用）；本地开发使用 Bun。

示例

连接后，Agent 可以回答这类问题：

• “上周，计数器 12345678 获得了多少次访问和多少位用户？按流量来源细分。” → run_report，参数为 metrics: ["ym:s:visits","ym:s:users"]、 dimensions: ["ym:s:lastsignTrafficSource"]。
• “比较本周和上周的自然转化量。” → run_comparison （服务返回 A、B 和差值）。
• “访客使用哪些操作系统？让我进一步查看 Windows 版本。” → run_drilldown，然后再次调用并传入 parentId。
• “我有哪些计数器？” → get_metadata。
• “列出此计数器的目标，然后显示‘购买’目标上周的转化情况。” → 调用 describe_counter（include: ["goals"]）获取目标 ID，然后调用 run_report，并传入 ym:s:goal<id>conversionRate。
• “导出上个月包含落地页和引荐来源的原始会话，以便离线 分析。” → 调用 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