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

随后，这两个写入工具会失败并返回一条指出缺少作用域的 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 之前，意外调用 delete-counter 会被只读令牌导致的 403 错误拦截。修复该 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	按设备、浏览器或操作系统划分的流量	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	数字	是	计数器 ID
metrics	字符串	是	以逗号分隔的指标（例如：ym:s:visits,ym:s:users）
dimensions	字符串	否	以逗号分隔的维度（例如：ym:s:trafficSource）
date_from	字符串	否	开始日期 YYYY-MM-DD（默认值：30 天前）
date_to	字符串	否	结束日期 YYYY-MM-DD（默认值：今天）
filters	字符串	否	筛选表达式（例如：ym:s:trafficSource=='organic'）
sort	字符串	否	排序字段；添加 - 前缀表示降序
limit	数字	否	最大结果数（默认值：10）

默认日期范围

未指定 date_from 和 date_to 时，所有报告工具默认使用最近 30 天的数据。

数据抽样

对于大型数据集，Metrika Stat API 可能会返回抽样数据。应用抽样时，响应中会包含一条说明，指出数据为近似值。

许可证

MIT