内容
<div align="center">
# Umami 分析 MCP 服务器
**用日常语言与您的 [Umami](https://umami.is) 网络分析工具交流。**
让 Claude 拉取您的统计数据，识别趋势，跟踪用户旅程，并构建仪表盘，无需 SQL，无需点击图表。
[](https://github.com/MurkyPuma/umami-mcp-server/actions/workflows/ci.yml)
[](LICENSE)
[](https://github.com/astral-sh/ruff)
[](https://github.com/MurkyPuma/umami-mcp-server/pulls)
</div>
这是一个 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，连接 Umami 到任何 MCP 客户端（Claude Desktop, Cursor 等）。提问，模型选择正确的分析调用，读取数据并回答，然后您可以继续：深入挖掘，比较范围，或让它组装一个完整的仪表盘。
它是 [`jakeyShakey/umami_mcp_server`](https://github.com/jakeyShakey/umami_mcp_server) 的现代化、依赖轻量级重写：FastMCP、异步 HTTP 客户端、微小的核心安装、可选的重功能和测试套件。参见 [`CHANGELOG.md`](CHANGELOG.md) 以获取完整的精神差异。
## 看看它的实际操作
```text
您： 哪些页面在上周带来了最多的流量，它们来自哪里？
Claude: （get_websites → get_website_metrics type=url → get_website_metrics type=referrer）
您上周的热门页面是 /pricing、/blog/getting-started 和 /。大部分流量来自 Google，然后是一个 Hacker News 线程，最后是直接访问。
想要我按国家或设备划分 /pricing 访问者吗？
您： 是的，并显示一个典型的 /pricing 访问者在离开前做了什么。
Claude: （get_website_metrics type=country → get_session_ids → get_tracking_data）
...
```
模型驱动工具，您只需提问。
## 您可能想要它的原因
- **日常语言分析。** 无需导航仪表盘或编写查询。
- **默认情况下轻量级。** 核心安装仅包括 `mcp`、`httpx` 和 `python-dotenv`。除非您选择，否则无需 torch 或无头浏览器。
- **异步和非阻塞。** Umami 客户端基于 `httpx.AsyncClient`。
- **适用于自托管或 Umami Cloud。** API 密钥或用户名/密码身份验证。
- **诚实地讲质量。** 纯函数测试套件加上 CI（ruff + pytest）适用于 Python 3.10 至 3.13。
## 工具
| 工具 | 返回内容 | 需要 |
| --- | --- | --- |
| `get_websites` | 您的网站及其 ID（从这里开始） | 核心 |
| `get_website_stats` | 页面浏览量、访客、访问次数、跳出率、总时间 | 核心 |
| `get_website_metrics` | 按 URL、引荐来源、浏览器、操作系统、设备、国家或事件划分 | 核心 |
| `get_pageview_series` | 页面浏览量/会话时间序列（小时/天/月） | 核心 |
| `get_active_visitors` | 当前实时访客人数 | 核心 |
| `get_session_ids` | 指定范围内的唯一会话 ID，可选按事件过滤 | 核心 |
| `get_tracking_data` | 一个会话的完整活动时间线 | 核心 |
| `get_html` | 实时页面的原始 HTML（HTTP GET，无 JS） | 核心 |
| `get_docs` | 跨多个用户旅程的语义搜索 | `[rag]` |
| `get_screenshot` | 实时页面的渲染截图 | `[screenshot]` |
还有一个 **创建仪表盘** 的提示，引导模型为网站和日期范围构建一个完整的仪表盘。日期参数接受 `YYYY-MM-DD` 或 `YYYY-MM-DD HH:MM:SS`，并被解释为 UTC。
## 快速开始
需要 Python 3.10+。
**1. 安装**
```bash
pip install "git+https://github.com/MurkyPuma/umami-mcp-server.git"
```
**2. 添加到 Claude Desktop**
编辑您的配置文件：
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"umami": {
"command": "umami-mcp-server",
"env": {
"UMAMI_API_URL": "https://cloud.umami.is",
"UMAMI_API_KEY": "your-api-key"
}
}
}
}
```
**3. 重启 Claude Desktop** 并询问类似 *"列出我的网站和上周的访客。"* 工具出现在工具（锤子）图标下。
> 如果 `umami-mcp-server` 不在 Claude Desktop 的 `PATH` 中，请使用该控制台脚本的绝对路径（例如 `/path/to/.venv/bin/umami-mcp-server`），或将 `"command"` 设置为您的 Python 解释器，并使用 `"args": ["-m", "umami_mcp"]`。
## 可选功能（额外）
重型、情景工具是可选的，以便默认安装保持较小。
```bash
# 语义旅程搜索（get_docs）。拉取 torch 尺寸的轮子。
pip install "umami-mcp-server[rag] @ git+https://github.com/MurkyPuma/umami-mcp-server.git"
# 渲染截图（get_screenshot）。然后安装浏览器。
pip install "umami-mcp-server[screenshot] @ git+https://github.com/MurkyPuma/umami-mcp-server.git"
playwright install chromium
# 所有内容
pip install "umami-mcp-server[all] @ git+https://github.com/MurkyPuma/umami-mcp-server.git"
```
如果没有额外的工具，它仍然会出现，但会返回一行安装提示而不是失败，因此不会破坏任何东西。
## 配置
将这些设置为环境变量（在 MCP 客户端配置文件中）或在本地 `.env` 中（参见 [`.env.example`](.env.example)）。
| 变量 | 必需 | 描述 |
| --- | --- | --- |
| `UMAMI_API_URL` | 是 | 您的 Umami 基本 URL，例如 `https://cloud.umami.is` |
| `UMAMI_API_KEY` | 其中之一 | API 密钥，作为 `x-umami-api-key` 发送（Umami Cloud / 新的自托管） |
| `UMAMI_USERNAME` / `UMAMI_PASSWORD` | 其中之一 | 交换为承载令牌的凭证 |
| `UMAMI_TEAM_ID` | 否 | 如果设置，`get_websites` 列出该团队的站点；否则是您的站点 |
| `UMAMI_TIMEOUT` | 否 | 每个请求的超时时间（秒，默认为 30） |
提供 **或者** `UMAMI_API_KEY`，**或者** `UMAMI_USERNAME` 和 `UMAMI_PASSWORD`。
## 开发
```bash
git clone https://github.com/MurkyPuma/umami-mcp-server.git
cd umami-mcp-server
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest # 运行测试
ruff check . # 检查代码风格
```
无需实时 Umami 即可测试：异步客户端通过 `httpx.MockTransport` 进行锻炼，RAG 测试涵盖纯粹的块状/排名助手（嵌入式模型未在 CI 中加载）。
```
src/umami_mcp/
config.py # 环境变量 -> 设置（纯粹，无副作用）
dates.py # 日期字符串 -> UTC unix 毫秒（纯粹）
client.py # 异步 httpx Umami 客户端（身份验证、重试、端点）
web.py # 通过 httpx 获取 HTML；可选的 Playwright 截图
rag.py # 可选的语义搜索（sentence-transformers + numpy）
server.py # FastMCP 工具 + 创建仪表盘提示
__main__.py # 入口点
```
## 贡献
问题和 PR 均欢迎。代码库很小，测试速度很快；一个好的初始贡献是添加一个尚未涵盖的 Umami 端点的工具。
如果这为您节省了一次访问 Umami 仪表盘的旅程，⭐ 帮助其他人找到它。
## 鸣谢
[jakeyShakey](https://github.com/jakeyShakey/umami_mcp_server) 的原始概念和首个实现。遵循 [MIT](LICENSE) 许可。
