内容
# Umami MCP
[](https://github.com/upnorthmedia/umami-mcp/actions/workflows/ci.yml)
一个小型的、只读的 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器，用于自托管的 [Umami](https://umami.is/) 分析。
使用托管的 Streamable HTTP 端点，凭证保存在本地环境中，或者在标准输入/输出上本地运行服务器。提供 Umami URL 和用户名/密码凭证或 bearer token；它处理登录并提供一个专注的分析工具集。
## 托管快速入门
公共端点是：
```text
https://umami-mcp-production-6324.up.railway.app/mcp
```
在启动 Codex 或 Claude Code 的环境中设置这些变量：
```text
UMAMI_URL=https://analytics.example.com
UMAMI_USERNAME=admin
UMAMI_PASSWORD=your-password
```
### Claude Code
运行一次以安装托管的 MCP：
```bash
claude mcp add-json --scope user umami '{"type":"http","url":"https://umami-mcp-production-6324.up.railway.app/mcp","headers":{"X-Umami-URL":"${UMAMI_URL}","X-Umami-Username":"${UMAMI_USERNAME}","X-Umami-Password":"${UMAMI_PASSWORD}"}}'
```
运行 `claude mcp get umami` 以检查配置，然后在 Claude Code 中使用 `/mcp` 验证连接。
### Codex
将以下内容添加到 `~/.codex/config.toml`：
```toml
[mcp_servers.umami]
url = "https://umami-mcp-production-6324.up.railway.app/mcp"
[mcp_servers.umami.env_http_headers]
X-Umami-URL = "UMAMI_URL"
X-Umami-Username = "UMAMI_USERNAME"
X-Umami-Password = "UMAMI_PASSWORD"
```
重启 Codex，然后使用 `/mcp` 或 `codex mcp list` 验证服务器。
环境变量名称存储在客户端配置中；它们的值在运行时添加到 HTTPS 请求头中。托管服务使用该请求的凭证，不会持久化它们。托管服务必然在内存中接收它们，因此如果您不希望凭证传输到由 Up North Media 运营的基础设施，请使用本地标准输入/输出选项。
### 使用现有的 Umami token
用一个 token 头替换用户名和密码头：
```text
X-Umami-Token: your-bearer-token
```
对于 Claude Code，设置 `"X-Umami-Token":"${UMAMI_TOKEN}"`。对于 Codex，在 `env_http_headers` 下设置 `X-Umami-Token = "UMAMI_TOKEN"`。
## 要求
- Node.js 20 或更新版本
- 官方自托管 Umami v2 或 v3 实例
- 具有访问您要查询的网站的 Umami 用户
支持共享的 v2/v3 读取端点。Umami 分叉或较旧版本可能会更改其 API 合同；API 错误会明确返回，而不是被隐藏。
## 本地标准输入/输出设置
### Codex
将以下内容添加到 `~/.codex/config.toml`：
```toml
[mcp_servers.umami]
command = "npx"
args = ["-y", "github:upnorthmedia/umami-mcp"]
[mcp_servers.umami.env]
UMAMI_URL = "https://analytics.example.com"
UMAMI_USERNAME = "admin"
UMAMI_PASSWORD = "your-password"
```
重启 Codex，然后使用 `/mcp` 或 `codex mcp list` 验证服务器。
### Claude Code 和其他标准输入/输出客户端
使用等效的 MCP 服务器配置：
```json
{
"mcpServers": {
"umami": {
"command": "npx",
"args": ["-y", "github:upnorthmedia/umami-mcp"],
"env": {
"UMAMI_URL": "https://analytics.example.com",
"UMAMI_USERNAME": "admin",
"UMAMI_PASSWORD": "your-password"
}
}
}
}
```
确切的设置文件位置因 MCP 客户端而异。对于 Claude Code，此配置可以存储在 `.mcp.json` 中或使用 `claude mcp add-json` 添加。
## 认证
推荐使用凭证认证，因为服务器可以在 Umami 会话令牌过期时重新登录：
```text
UMAMI_URL=https://analytics.example.com
UMAMI_USERNAME=admin
UMAMI_PASSWORD=your-password
```
您也可以提供现有的 bearer token：
```text
UMAMI_URL=https://analytics.example.com
UMAMI_TOKEN=your-bearer-token
```
选择一种认证方法。服务器拒绝部分凭证或令牌与用户名/密码凭证组合。
`UMAMI_URL` 可以是实例根、基本路径安装或 API URL 本身：
```text
https://analytics.example.com
https://example.com/analytics
https://analytics.example.com/api
```
## 工具
| 工具 | 用途 |
| --- | --- |
| `list_websites` | 列出可用于认证用户的网站 |
| `get_website` | 获取一个网站的详细信息 |
| `get_active_visitors` | 获取最近五分钟内活跃的访客 |
| `get_stats` | 获取汇总的页面浏览量、访客、访问次数、跳出率和时间 |
| `get_pageviews` | 获取页面浏览量和会话时间序列 |
| `get_metrics` | 按路径、来源、浏览器、设备、国家、事件或其他支持的指标细分流量 |
| `get_events` | 列出页面浏览量和自定义事件详细信息 |
| `get_sessions` | 列出访客会话 |
| `get_realtime` | 获取最近 30 分钟的活动 |
每个工具在其 MCP 注解中都标记为只读且无破坏性。
日期输入接受 Unix 时间戳（毫秒）或 ISO 8601 日期时间。过滤器传递给 Umami，以便服务器支持特定于版本的字段。例如，Umami v3 将其页面筛选器称为 `path`，而较旧的 v2 安装可能使用 `url`。
## 本地开发
```bash
git clone https://github.com/upnorthmedia/umami-mcp.git
cd umami-mcp
npm install
npm run check
```
构建并运行标准输入/输出服务器：
```bash
npm run build
UMAMI_URL=https://analytics.example.com \
UMAMI_USERNAME=admin \
UMAMI_PASSWORD=your-password \
node dist/index.js
```
测试使用真正的本地 HTTP 服务器和 MCP SDK 的链接内存传输。它们不会联系您的 Umami 实例。
在本地运行托管传输：
```bash
npm run build
PORT=3000 npm start
```
其 MCP 端点是 `http://localhost:3000/mcp`，其健康端点是 `http://localhost:3000/health`。托管请求模式仍然需要目标 Umami 实例使用 HTTPS 和公开可路由的地址。
## Railway 部署
包含的 `Dockerfile` 和 `railway.toml` 已准备好投入生产：
```bash
railway init
railway add --service umami-mcp
railway up
railway domain --port 3000
```
Railway 变量中不应包含 Umami 凭证。每个 MCP 客户端都发送其自己的本地配置凭证与请求。
## 安全
- 本地标准输入/输出凭证从环境变量中读取，工具永远不会返回这些凭证。
- 托管凭证在请求头中到达，由用户的本地 MCP 客户端填充，服务永远不会记录或持久化这些凭证。
- 公共 HTTP 服务是无状态的，对于每个 MCP 请求都是如此，不会持久化 Umami 凭证或会话令牌。
- 托管目标必须使用 HTTPS，只能解析为公共网络地址，不能包含嵌入式 URL 凭证，不能重定向。
- 浏览器发起的请求被拒绝，MCP 请求根据客户端地址进行速率限制。
- 服务器仅公开分析读取；它没有创建、更新、删除或重置工具。
- API 错误包括状态和 Umami 的错误消息，但不转储请求头或凭证。
## 许可证
[MIT](LICENSE)
