内容
# @byterover/umami-mcp
一款最小化的、**只读**的 [模型上下文协议](https://modelcontextprotocol.io) 服务器，用于 [Umami](https://umami.is) 分析 - 云端或自托管。
它通过标准输入/输出公开了一组小型读取工具（列出站点、统计数据、时间序列、顶部指标、实时访客），因此像 [Grove](https://github.com/campfirein/grove) 这样的MCP客户端可以让代理回答有关您的网络分析的问题。它**不执行写入操作** - 按设计，没有创建/更新/删除工具。
## 为什么存在
社区Umami MCP服务器存在但使用率不高，也没有被我们信任的分析凭证审查。这是byterover的第一方、源代码公开的包装器：足够小，可以从头到尾阅读，只有读取权限，并以出处发布。我们在自己的登陆页面分析中使用它。
## 安装
```sh
npx @byterover/umami-mcp
```
## 配置
通过环境变量选择**一种**模式。
**Umami 云端** - 在 [cloud.umami.is](https://cloud.umami.is) （设置 → API 密钥）创建只读API密钥：
```sh
UMAMI_API_KEY=您的_api_key
```
**自托管** - 指向您的实例并提供登录信息：
```sh
UMAMI_API_URL=https://umami.example.com
UMAMI_USERNAME=您的用户名
UMAMI_PASSWORD=您的密码
```
高级：`UMAMI_API_URL` 覆盖基本主机（云端默认为 `https://api.umami.is`），`UMAMI_API_PATH` 覆盖路径前缀（云端为 `/v1`，自托管为 `/api`）。
## 与 Grove 一起使用
将其添加到您的 `mcp.json` 中作为标准输入/输出服务器（固定版本；通过 `${VAR}` 引用将密钥保留在 `.env` 中）：
```json
{
"mcpServers": {
"umami": {
"command": "npx",
"args": ["-y", "@byterover/umami-mcp@0.1.0"],
"env": { "UMAMI_API_KEY": "${UMAMI_API_KEY}" }
}
}
}
```
工具在 Grove 中显示为 `umami__list_websites`、`umami__website_stats` 等。
## 工具
十三项读取工具涵盖了几乎所有的 Umami 分析读取功能 - 整合（一个 `metrics` 工具跨越约 10 个维度；`explore_event_data` 将五个端点折叠在 `mode` 后面），从不直接映射 REST API 1:1。
**发现**
| 工具 | 返回内容 |
| --- | --- |
| `list_websites` | 这些凭证可见的网站（id，名称，域名）。从这里开始。 |
| `data_range` | 最早/最新的带有数据的 timestamp - 在查询范围之前调用。 |
**流量和趋势**
| 工具 | 返回内容 |
| --- | --- |
| `website_stats` | 页面浏览量、访客数、访问次数、跳出率、总时间（带有前一时期）。 |
| `pageviews_series` | 页面浏览量/会话时间序列，按小时/天/月/年分组。 |
| `realtime` | 最近 ~30 分钟的实时活动（活跃访客、最近浏览/事件）。 |
**细分和事件**
| 工具 | 返回内容 |
| --- | --- |
| `metrics` | 某一维度的顶部值（网址、来源、浏览器、国家、事件等）；`expanded=true` 添加参与度。 |
| `events_series` | 在一定范围内的自定义事件时间序列。 |
| `explore_event_data` | 深入事件属性/值（`mode`：事件/属性/字段/统计/值）。 |
**会话和旅程**
| 工具 | 返回内容 |
| --- | --- |
| `list_sessions` | 单个访客会话（分页，可搜索）。 |
| `session_detail` | 一个会话的摘要 + 活动日志 + 自定义属性。 |
**分析**（计算读取，POST - 仍然只读）
| 工具 | 返回内容 |
| --- | --- |
| `funnel_report` | 跨有序步骤（路径/事件）的转换漏斗。 |
| `retention_report` | 在范围内返回访客的留存率（需要时区）。 |
| `journey_report` | 在起始和（可选）结束步骤之间的常见导航路径。 |
范围工具接受 ISO `startAt`/`endAt`；报告工具接受 ISO `startDate`/`endDate`（例如 `2026-07-01`）。省略它们以获取最近 7 天的数据。
## 开发
```sh
pnpm install
pnpm build # tsc → dist/
pnpm typecheck
pnpm test # 无密钥，无网络
pnpm lint
```
## 许可证
[Elastic License 2.0](./LICENSE) — 版权所有 byterover.
