umami

英语 | 韩语

umami-mcp

适用于 Umami Analytics v3 API 的 Model Context Protocol 服务。 它支持通过用户名/密码或 API 密钥进行自托管认证，以及 Umami Cloud API 密钥，并提供分析、采集、管理，以及 boards、links、pixels、segments、session replay、shares、 exports、performance 和 revenue 等 v3 功能系列。

此版本不会声称涵盖 Umami 的所有私有路由。其工具对应有文档记录的 API，包括 Umami 3.4 API 密钥认证。 报告工具使用 Umami 3.4 仍支持的旧版报告契约。

要求

• Node.js 20 或更高版本，且与 MCP SDK 已安装的运行时依赖项匹配
• 与 Umami v3.3 兼容的自托管实例（API 密钥、会话属性分段和注释需要 3.4+），或已启用相应路由的 Umami Cloud

安装

npm install -g @mikusnuz/umami-mcp

或者直接运行：

npx -y @mikusnuz/umami-mcp

配置

自托管

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "@mikusnuz/umami-mcp"],
      "env": {
        "UMAMI_URL": "https://analytics.example.com",
        "UMAMI_USERNAME": "admin",
        "UMAMI_PASSWORD": "your-password"
      }
    }
  }
}

UMAMI_URL 是实例的源地址。可以包含末尾的 /api，但不是必需的。

在 Umami 3.4+ 中，前往 Settings → API keys 创建 API 密钥，并将 UMAMI_USERNAME 和 UMAMI_PASSWORD 替换为 UMAMI_API_KEY。将 UMAMI_MODE 设为 self-hosted，以显式选择部署模式。

Umami Cloud

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "@mikusnuz/umami-mcp"],
      "env": {
        "UMAMI_API_KEY": "your-cloud-api-key"
      }
    }
  }
}

Cloud 管理调用默认使用 https://api.umami.is/v1；工具路径会将自托管的 /api/... 路径 转换为 Cloud 的 /v1/... 路径。需要指定 Cloud 区域时，将 UMAMI_URL 设为 https://api.umami.is/v1/us 或 https://api.umami.is/v1/eu。 若 Cloud API 代理使用其他主机名，也请将 UMAMI_MODE 设为 cloud。

环境变量

变量	何时必需	说明
UMAMI_MODE	可选	self-hosted 或 cloud；省略时自动检测
UMAMI_URL	自托管	实例源地址；Cloud 可选
UMAMI_USERNAME	未使用自托管 API 密钥时	登录用户名
UMAMI_PASSWORD	未使用自托管 API 密钥时	登录密码
UMAMI_API_KEY	Cloud 必需；自托管 3.4+ 可选	Bearer API 密钥
UMAMI_COLLECTOR_URL	可选	用于公共采集、分享、心跳和录制器路由的独立主机

对于 Cloud，采集器默认使用 https://cloud.umami.is。对于自托管 Umami，默认使用 UMAMI_URL。 未设置 UMAMI_URL 的 API 密钥，或指向 api.umami.is 的 URL，会选择 Cloud。 任何其他已配置的 URL 都会选择自托管模式，即使使用的是 API 密钥。

身份验证和公共路由

管理和分析工具会发送 bearer 令牌。使用密码时，客户端会按需登录自托管实例， 并缓存返回的 JWT。 两种部署类型下，API 密钥都会直接作为 bearer 凭据发送。

公共采集路由无需凭据：

• send_event、send_identify、send_performance
• batch_events（原始 JSON 数组，最多 500 项）
• heartbeat、get_share、get_recorder_config

如果自托管登录提示需要双重身份验证，请使用当前 TOTP 或备用代码调用 complete_two_factor_login，然后重试原工具。自托管 Umami 还提供设置和策略工具。

Umami Cloud 不支持通过 API 密钥访问 /me/password、/users 或 /users/*。 这些工具仅适用于自托管实例。

工具组

领域	代表性工具
网站	list_websites、CRUD、重置、转移给用户/团队、回放配置
分析	get_stats、get_pageviews、get_metrics、get_events、get_sessions、事件序列
事件/会话数据	事件值、字段、属性、值、会话活动
数据收集	事件/页面浏览、识别、性能、原始批次、链接/像素事件
报告	已保存报告的 CRUD，以及用于归因、细分、漏斗、目标、热图、用户旅程、性能、留存、收入和 UTM 的 run_report
看板	列表、CRUD、克隆和团队看板
链接和像素	列表、CRUD、图表和收集事件
细分	细分/群组列表和 CRUD
注释（3.4+）	list_annotations、get_annotation、create_annotation、update_annotation、delete_annotation
回放	录制器配置、回放列表/详情、已保存回放、会话回放
分享和导出	公开分享解析、托管网站分享、更新/删除、CSV ZIP 导出
收入	统计数据、图表、指标和收入会话
用户和团队	当前管理员用户及团队成员资格/转移路由
2FA	登录完成、注册、停用和管理员强制策略
实时数据	get_realtime

使用 MCP tools/list 获取完整的机器可读列表和架构。

重要的 v3 契约细节

• 页面浏览以 { "type": "event" } 的形式发送，不带事件 name；旧的 pageview 类型已不再有效。
• /api/batch 接收作为原始数组传入的事件对象，而不是 { "events": [...] }。工具会返回 Umami 的 processed、errors 和 每项的 details 字段，并将部分失败标记为 MCP 错误结果。
• 数据收集调用会按 Umami 的要求设置稳定的非机器人 User-Agent 标头；send_event 和批次项也可以在负载中提供访客的 userAgent 和可信的服务器端 ip。
• 分析 URL 筛选器和页面指标使用 path；旧的 url 指标已移除。主机聚合使用 hostname。
• 即使省略了对应的命名选项，额外的 filters 也会保留。明确提供的命名选项优先于 filters。
• 细分的创建和更新支持 filters、sessionPropertyFilters、match、dateRange 和 action。会话属性数据类型为 1=字符串、 2=数字、3=布尔值、4=日期、5=数组。群组不支持会话属性筛选器。未知的嵌套字段会被拒绝，而不会被静默丢弃。
• 注释需要 Umami 3.4+，写入操作还需要网站编辑权限。请提供 ISO 日期或时间戳、长度为 1–500 个字符的备注，以及可选的 allDay （默认值为 true）。更新会替换全部三个字段；列表日期筛选器要求同时提供以毫秒为单位的 startAt 和 endAt。较旧的服务端可能会返回 404。
• 支持的时间单位为 minute、hour、day、month 和 year。
• get_event_series 和 get_sessions_weekly 需要 IANA 时区。
• list_reports 需要 websiteId；报告执行会发送 { websiteId, type, filters, parameters }。
• 团队网站成员资格通过 transfer_website 更改；已移除的团队网站 POST/DELETE 路由不会公开。

开发

npm install
npm test

npm test 会构建 TypeScript 服务端、检查 Cloud/可自托管 URL 和身份验证行为、验证原始公开批次请求和 2FA 登录流程，并验证关键 MCP 架构。

Official references

• Umami API overview
• Authentication
• Cloud API keys
• Sending statistics
• Website statistics
• Reports
• Cloud/API changelog
• Umami v3.4.0 server source
• Report API compatibility

License

MIT