Ymetrika MCP

MCP数据服务

提供方 NNSTD-cloud-ru-hack-2025

数据服务 stdio · 本地进程 OAuth 授权 社区 / 第三方
查看接入方式

Yandex Metrika MCP服务器提供通过标准MCP接口查询分析数据、生成报告和访问Yandex Metrika洞察的工具。

一句话选型结论

按资料字段整理

Ymetrika MCP 属于数据服务类 MCP 服务器,stdio · 本地进程,OAuth 授权,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类数据服务 传输方式stdio · 本地进程 鉴权OAuth 授权 部署方式本地部署
GitHub 星标 0 仓库热度,无公开仓库时显示未标注
工具数 6 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

数据服务
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量6暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

适用场景

数据分析Python本地部署报告生成流量统计用户行为分析网站分析

安装与配置

stdio · 本地进程 OAuth 授权
客户端在本机拉起子进程,数据不出本机
uv run python src/server.py

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Python,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 6 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
数据库查询

用自然语言查库、取数,不用手写 SQL。

数据同步与清洗

把多来源数据拉到一处做整理。

报表取数

按口径快速拉出统计结果。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 6 个工具,职责相对集中,接入后不容易误操作。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好OAuth 授权对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在数据服务场景里让模型直接调用外部能力的人。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Ymetrika MCP当前 6 stdio · 本地进程 本地部署 有 2026-05-17
Memory 9d25f64e 9 未标注 未标注 无 2026-05-17
Getzep MCP 9 stdio · 本地进程 本地部署 有 2026-05-17
anything-llm 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Prisma MCP Server 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Astr Bot 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

数据服务
字段来自项目仓库与公开索引,中文说明由本站标注
提供方NNSTD-cloud-ru-hack-2025上游标注的维护方 NNSTD-cloud-ru-hack-2025
分类数据服务本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式OAuth 授权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Python本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

13.4 KB
来自项目仓库与上游目录的原文,未做删改

Yandex Metrika MCP服务器

MCP(模型上下文协议)服务器 Yandex Metrika 分析和报告。该服务器提供用于查询分析数据、生成报告和通过标准化MCP界面访问Yandex Metrika见解的工具。

🚀 快速开始

先决条件

  • Python 3.12+
  • 紫外线 (推荐)或pip
  • Docker(可选,用于容器化部署)

地方发展

  1. 克隆仓库```bash
    git clone
    cd ymetrika-mcp

2. **安装uv(如果尚未安装)**```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
  1. 安装依赖项```bash
    uv sync

4. **配置环境**```bash
cp .env.example .env
# Edit .env with your configuration
  1. 运行服务器```bash
    uv run python src/server.py

服务器将于启动 `http://0.0.0.0:8000` 默认情况下。

### Docker部署

1. **塑造形象**```bash
docker build -t yandex-metrika-mcp .
  1. 运行容器```bash
    docker run -p 8000:8000 \
    -e OTEL_ENDPOINT=http://your-otel-collector:4318/v1/traces \
    -e YANDEX_API_KEY=your_api_key_here \
    yandex-metrika-mcp

## 📡 端点

运行后,服务器将公开以下端点:

- **MCP协议**: `http://0.0.0.0:8000/mcp` -用于工具调用的主MCP端点
- **指标**: `http://0.0.0.0:8000/metrics` -Prometheus指标端点
- **健康检查**: `http://0.0.0.0:8000/health` -服务器运行状况

## 🔧 可用工具

### `ping` -Hello World验证工具

用于验证MCP服务器功能的诊断工具。

**目的**:验证MCP传输、日志记录、进度报告、跟踪和指标。

**参数**:

- `message` (可选,字符串):要回显的短信

**退货**:

- 文本: `"pong"` 或 `"pong: "`
- 具有状态和可选回声的结构化数据

**示例用法**:```json
{
"tool": "ping",
"parameters": {
"message": "hello world"
}
}

响应:```json
{
"content": [
{
"type": "text",
"text": "pong: hello world"
}
],
"structured_content": {
"status": "ok",
"message": "pong: hello world",
"echo": "hello world"
}
}


### Yandex Metrika工具

以下工具提供对Yandex Metrika分析数据的访问:

#### `get_account_info` -柜台信息

从YandexMetrika管理API获取账户和柜台信息。

**目的**:检索计数器元数据,包括名称、站点URL、状态、权限和目标列表。

**参数**:

- `counter_id` (必填,整数):Yandex Metrika计数器标识符

**退货**:

- 文本:人类可读的计数器信息
- 带计数器元数据的结构化数据

**示例用法**:```json
{
"tool": "get_account_info",
"parameters": {
"counter_id": 12345678
}
}

get_visits -交通统计

使用可选日期范围从Yandex Metrika获取访问统计数据。

目的:检索流量统计数据,包括访问量、用户和页面浏览量。

参数:

  • counter_id (必填,整数):Yandex Metrika计数器标识符
  • date_from (可选,字符串):开始日期(YYYY-MM-DD或相对格式)。默认值:6天前
  • date_to (可选,字符串):结束日期(YYYY-MM-DD或相对格式)。默认值:今天
  • metrics (可选,字符串):逗号分隔的指标。默认值:ym:s:访问量,ym:s:用户,ym:s:页面浏览量

退货:

  • 文本:人类可读的访问统计
  • 具有流量指标的结构化数据

示例用法:```json
{
"tool": "get_visits",
"parameters": {
"counter_id": 12345678,
"date_from": "2025-12-01",
"date_to": "2025-12-07"
}
}


#### `get_traffic_sources_types` -交通源分析

从Yandex Metrika获取流量来源分析。

**目的**:按来源类型(直接、搜索、推荐、社交等)检索流量明细。

**参数**:

- `counter_id` (必填,整数):Yandex Metrika计数器标识符
- `date_from` (必填,字符串):开始日期(YYYY-MM-DD或相对格式)
- `date_to` (必填,字符串):结束日期(YYYY-MM-DD或相对格式)
- `dimensions` (可选,字符串):逗号分隔的维度。默认值:ym:s:trafficSource
- `metrics` (可选,字符串):逗号分隔的指标。默认值:ym:s:visits,ym:s:users
- `limit` (可选,整数):要返回的最大行数。默认值:100

**退货**:

- 文本:人类可读的流量来源细分
- 具有源分布的结构化数据

**示例用法**:```json
{
"tool": "get_traffic_sources_types",
"parameters": {
"counter_id": 12345678,
"date_from": "2025-12-01",
"date_to": "2025-12-07"
}
}

get_user_demographics -用户人口统计报告

从Yandex Metrika获取用户人口统计报告(性别、年龄分布)。

目的检索人口统计数据,包括性别分布和年龄组。

参数:

  • counter_id (必填,整数):Yandex Metrika计数器标识符
  • date_from (必填,字符串):开始日期(YYYY-MM-DD或相对格式)
  • date_to (必填,字符串):结束日期(YYYY-MM-DD或相对格式)
  • dimensions (可选,字符串):逗号分隔的维度。默认值:ym:s:性别,ym:s:年龄
  • metrics (可选,字符串):逗号分隔的指标。默认值:ym:s:visits,ym:s:users
  • limit (可选,整数):要返回的最大行数。默认值:100

退货:

  • 文本:人类可读的人口统计细分
  • 具有性别和年龄分布的结构化数据

示例用法:```json
{
"tool": "get_user_demographics",
"parameters": {
"counter_id": 12345678,
"date_from": "2025-12-01",
"date_to": "2025-12-07"
}
}


#### `get_goals_conversion` -目标和转化率

从Yandex Metrika获取目标完成数据和转化率。

**目的**:使用Yandex Metrika的转换预设检索目标完成数据和转换率。

**参数**:

- `counter_id` (必填,整数):Yandex Metrika计数器标识符
- `date_from` (必填,字符串):开始日期(YYYY-MM-DD或相对格式)
- `date_to` (必填,字符串):结束日期(YYYY-MM-DD或相对格式)
- `goal_id` (可选,整数):用于筛选结果的特定目标ID
- `dimensions` (可选,字符串):逗号分隔的维度。默认值:ym:s:goal
- `metrics` (可选,字符串):逗号分隔的指标。默认值:ym:s:sumGoalReachesAny,ym:s:anyGoalConversionRate
- `limit` (可选,整数):要返回的最大行数。默认值:100

**退货**:

- 文本:人类可读的目标绩效和转化率
- 具有目标完成情况和比率的结构化数据

**示例用法**:```json
{
"tool": "get_goals_conversion",
"parameters": {
"counter_id": 12345678,
"date_from": "2025-12-01",
"date_to": "2025-12-07",
"goal_id": 174633455
}
}

⚙️ 配置

环境变量

这 ENVIRONMENT 变量决定应用程序的运行时模式。可以设置为 development (默认)或 production。在开发模式下,服务器以宽松的验证运行,而在生产环境中,变量必须设置为 production 强制验证 YANDEX_API_KEY.

所有配置都通过环境变量进行管理。看 .env.example 查看完整列表。

服务器配置

变量 类型 默认值 描述
PORT 整数 8000 服务器端口号(1024-65535)
LOG_LEVEL 字符串 INFO 日志记录级别(调试、信息、警告、错误、严重)
ENVIRONMENT 字符串 development 运行时模式(development 或 production)

开放遥测配置

变量 类型 默认值 描述
OTEL_ENDPOINT 字符串 (空) 用于跟踪的OTLP HTTP端点。如果未设置,则使用控制台导出器。
OTEL_SERVICE_NAME 字符串 yandex-metrika-mcp 用于跟踪的服务名称

Yandex 指标 API

变量 类型 默认值 描述
YANDEX_API_KEY 字符串 (空) Yandex OAuth令牌(从获取https://oauth.yandex.ru/)
YANDEX_COUNTER_ID 字符串 (空) 默认Metrika计数器ID
API_TIMEOUT 整数 30 API请求超时(以秒为单位)(1-300)
API_MAX_RETRIES 整数 3 API调用的最大重试次数(0-10)

🔐 Yandex Metrika身份验证

要使用Yandex Metrika工具,您需要通过以下方式获得OAuth令牌 metrika:read 范围:

  1. 获取OAuth令牌:
  • 访问 Yandex OAuth
  • 创建新应用程序或使用现有应用程序
  • 请求 metrika:read 范围
  • 生成OAuth令牌
  1. 设置环境变量:```bash
    export YANDEX_API_KEY=your_oauth_token_here

1. **查找您的柜台ID**:

- 登录到 Yandex Metrika
- 选择您的网站
- 计数器ID在URL和界面中可见

## 📊 可观测性

此服务器按照生产最佳实践实现了全面的可观察性。

### OpenTetry跟踪

所有工具调用都使用OpenTetry跨度进行跟踪,该跨度包含:

- 工具名称和参数
- 执行状态
- 错误详细信息(如有)
- 每个工具的自定义属性

**地方发展**:痕迹输出到控制台
**生产**:配置 `OTEL_ENDPOINT` 将痕迹发送给您的收藏家(Jaeger、Tempo等)

### 普罗米修斯指标

服务器在以下位置公开与Prometheus兼容的指标 `/metrics`:

#### `tool_calls_total`

工具调用计数器

- 标签: `tool_name`, `status` (已启动、成功、验证错误、错误)

#### `calculation_errors_total`

刀具执行错误计数器

- 标签: `tool_name`, `error_type` (验证、计算)

#### `api_calls_total`

外部API调用计数器(未来工具)

- 标签: `service`, `endpoint`, `status`

### 日志记录

带有表情符号指示器的结构化日志记录,可轻松进行可视化解析:

- 🏁 流程启动
- 🔍 验证
- 🎯 处理
- 📦 格式化
- ✅ 成功
- ❌ 错误

## 🏗️ 建筑

### 项目结构```
ymetrika-mcp/
├── src/
│   ├── mcp_instance.py      # Single FastMCP instance
│   ├── server.py            # Main entry point, tracing init
│   ├── config.py            # Configuration and environment
│   ├── metrics.py           # Prometheus metrics definitions
│   └── tools/               # MCP tools (one per file)
│       ├── __init__.py
│       ├── hello.py         # Ping tool
│       └── utils.py         # Shared utilities
├── openspec/                # OpenSpec change proposals
├── pyproject.toml           # Python project configuration
├── Dockerfile               # Container image
├── .env.example             # Environment template
├── env_options.json         # Environment documentation
├── mcp_tools.json           # Tool specifications
└── README.md                # This file

关键设计原则

  1. 单个FastMCP实例:所有工具都注册了一个 mcp 实例在 mcp_instance.py
  2. 每个文件一个工具:每个工具都位于其自己的文件中 src/tools/
  3. 异步一切:所有工具都是异步函数,使用 async def
  4. 类型安全:Pydantic Field 对于所有经过验证的参数
  5. 上下文日志记录:所有工具使用 ctx: Context 用于进度和日志记录
  6. 错误映射:标准MCP错误代码通过 McpError:
    - -32602:无效参数/验证错误
    - -32603:内部/意外错误
  7. 可观察性优先:每个工具上的OTel跨度和Prometheus指标
  8. 仅限流式HTTP:运输已锁定 streamable-http
  9. 安全:没有硬编码的秘密,非root Docker用户,没有文件系统写入

🔐 安全

  • 所有配置的环境变量(没有硬编码的秘密)

  • Docker容器以非root用户身份运行(mcp,UID 1000)

  • 没有运行时文件系统写入

  • 使用Pydantic进行输入验证

🧪 测试```bash

Run tests

uv run pytest

Run with coverage

uv run pytest --cov=src --cov-report=html

Type checking

uv run mypy src

Linting

uv run ruff check src
```

📚 开发指南

此项目遵循中定义的严格代理开发规则 AGENTS.md 和 .rules.关键要求:

  • 异步工具功能 和 async def
  • Pydantic场 用于参数验证
  • 上下文用法 (ctx: Context)用于记录和进度
  • 进度报告 0%、25%、50%、75%、100%
  • Mcp错误 对于标准代码的所有错误
  • OpenTetry跨度 包装工具逻辑
  • 普罗米修斯指标 可观察性

有关详细指南,请参阅:

  • AGENTS.md -代理开发规则
  • openspec/project.md -OpenSpec工作流
  • openspec/AGENTS.md -MCP特定标准

🗺️ 路线图

第一阶段:基础骨架✅

  • [x] 具有可流式传输http的基础服务器
  • [x] 你好,世界 ping 工具
  • [x] OpenTetry跟踪
  • [x] 普罗米修斯指标
  • [x] Docker支持

第二阶段:Yandex Metrika工具✅

  • [x] 计数器统计(get_account_info)
  • [x] 交通报告(get_visits)
  • [x] 交通来源分析(get_traffic_sources_types)
  • [x] 用户人口统计(get_user_demographics)
  • [x] 目标和转化(get_goals_conversion)

第3阶段:高级功能(未来)

  • []批量报告生成
  • []数据导出工具
  • []自定义仪表板
  • []多柜台支持

📖 参考文献

  • 模型上下文协议(MCP)
  • FastMCP框架
  • Yandex 指标 API
  • OpenTelemetry Python
  • Prometheus客户端Python

📝 许可证

MIT许可证-有关详细信息,请参阅许可证文件

🤝 贡献

欢迎投稿!请遵循OpenSpec工作流程:

  1. 在中创建更改建议 openspec/changes//
  2. 用场景定义需求
  3. 执行以下代理规则
  4. 更新文档(README.md, mcp_tools.json, env_options.json)
  5. 提交带有测试的PR

💬 支持

对于问题、疑问或功能请求,请在GitHub上打开问题。


内置于❤️ 使用FastMCP和OpenTetry

常见问题

7 问
答案由本站依据条目字段整理,不引用上游原文
Ymetrika MCP 怎么安装?

在客户端按下面的安装命令接入:uv run python src/server.py。装完在客户端配置里引用同一个包或端点。

Ymetrika MCP 怎么在客户端里配置?

它的传输方式未标注,在客户端 MCP 配置里按官方文档填写启动命令和参数,保存后重启客户端生效。

Ymetrika MCP 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Ymetrika MCP 需要 API Key 吗?

资料标注需要OAuth 授权认证,使用前准备好对应凭据,并按最小权限配置。

Ymetrika MCP 能提供哪些能力?

资料显示约 6 个工具;能力标签包括 数据分析、报告生成、Python。具体工具清单以官方文档为准。

Ymetrika MCP 需要什么运行环境?

运行时为 Python;属于本地进程,需要在本机装好运行环境。

Ymetrika MCP 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。