Ymetrika MCP

Yandex Metrika MCP服务器

](https://www.python.org/downloads/)  

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

🚀 快速开始

先决条件

• Python 3.12+
• 紫外线 （推荐）或pip
• Docker（可选，用于容器化部署）

地方发展

1. 克隆仓库

git clone 
cd ymetrika-mcp

1. 安装uv（如果尚未安装）

curl -LsSf https://astral.sh/uv/install.sh | sh

1. 安装依赖项

uv sync

1. 配置环境

cp .env.example .env
# Edit .env with your configuration

1. 运行服务器

uv run python src/server.py

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

Docker部署

1. 塑造形象

docker build -t yandex-metrika-mcp .

1. 运行容器

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: "
• 具有状态和可选回声的结构化数据

示例用法:

{
  "tool": "ping",
  "parameters": {
    "message": "hello world"
  }
}

响应:

{
  "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计数器标识符

退货:

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

示例用法:

{
  "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：页面浏览量

退货:

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

示例用法:

{
  "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

退货:

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

示例用法:

{
  "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

退货:

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

示例用法:

{
  "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

退货:

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

示例用法:

{
  "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 查看完整列表。

服务器配置

开放遥测配置

Yandex 指标 API

🔐 Yandex Metrika身份验证

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

1. 获取OAuth令牌:

- 访问 Yandex OAuth - 创建新应用程序或使用现有应用程序 - 请求 metrika:read 范围 - 生成OAuth令牌

1. 设置环境变量:

   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：内部/意外错误

1. 可观察性优先：每个工具上的OTel跨度和Prometheus指标
2. 仅限流式HTTP：运输已锁定 streamable-http
3. 安全：没有硬编码的秘密，非root Docker用户，没有文件系统写入

🔐 安全

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

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

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

• 使用Pydantic进行输入验证

🧪 测试

# 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