umami-mcp 是一个 Model Context Protocol（MCP）服务器，用于连接 Umami Analytics API。它基于 Umami Analytics v3 API 构建，支持自托管实例（用户名/密码或 API 密钥认证）以及 Umami Cloud（API 密钥认证）。该服务器提供对分析、数据收集、管理以及 v3 新特性（如看板、链接、像素、细分、会话回放、分享、导出、性能和收入）的访问。
主要能力：
- 提供 66 个工具、2 个资源和 2 个提示，覆盖 Umami 文档化的 API 路由。
- 支持自托管 Umami v3.3 兼容实例（API 密钥需要 3.4+）或 Umami Cloud。
- 认证方式：自托管可使用用户名/密码（懒登录并缓存 JWT）或 API 密钥；Cloud 使用 API 密钥。
- 公开收集路由无需凭证，包括 send_event、send_identify、send_performance、batch_events（原始 JSON 数组，最多 500 项）、heartbeat、get_share、get_recorder_config。
- 支持双因素认证：若自托管登录要求 2FA，可调用 complete_two_factor_login 并提供 TOTP 或备份码。
- 管理工具（如 /me/password、/users 等）仅适用于自托管实例，Cloud 不通过 API 密钥暴露这些路由。
使用方式：
- 需要 Node.js 18 或更高版本。
- 通过环境变量配置：UMAMI_URL 为实例源地址（可接受尾部 /api，但非必需）；UMAMI_USERNAME 和 UMAMI_PASSWORD 用于自托管密码认证；UMAMI_API_KEY 用于 API 密钥认证（Umami 3.4+ 可在设置中创建）；UMAMI_MODE 可显式设置为 self-hosted 或 cloud。
- 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，收集器默认使用 https://cloud.umami.is；自托管则默认使用 UMAMI_URL。仅提供 API 密钥而无 UMAMI_URL，或 URL 为 api.umami.is 时选择 Cloud；其他配置 URL 选择自托管模式。
- 管理及分析工具发送 bearer token；公开收集路由无需凭证。
- 可使用 MCP 的 tools/list 获取完整的机器可读工具列表和模式。
重要 v3 契约细节：
- 页面浏览发送为 { "type": "event" } 且无事件名称；旧的 pageview 类型不再有效。
- /api/batch 接收原始事件对象数组，而非 { "events": [...] }。工具返回 Umami 的 processed、errors 和逐项详情字段，并将部分失败标记为 MCP 错误结果。
- 收集器调用设置稳定的非机器人 User-Agent 头；send_event 和批量项也可在负载中提供访客的 userAgent 和受信任的服务器端 ip。
- 分析 URL 过滤器和页面指标使用 path；旧的 url 指标已移除。主机聚合使用 hostname。
- 支持的时间单位为 minute、hour、day、month、year。
- get_event_series 和 get_sessions_weekly 需要 IANA 时区。
- list_reports 需要 websiteId；报告执行发送 { websiteId, type, filters, parameters }。
- 团队网站成员关系通过 transfer_website 更改；已移除的团队-网站 POST/DELETE 路由不再暴露。
适用场景：
- 将 Umami 分析数据集成到 AI 助手或自动化工作流中。
- 通过 MCP 协议查询网站统计、会话、事件、报告等。
- 管理自托管 Umami 实例的用户、团队和设置。
- 利用 v3 特性进行高级分析，如会话回放、细分和收入跟踪。
限制：
- 需要 Node.js 18+ 和兼容的 Umami 实例或 Cloud 账户。
- 该版本有意不声称覆盖所有私有 Umami 路由，仅跟踪文档化的 API。
- 报告工具使用 Umami 3.4 仍支持的旧版报告契约。
- Cloud 不通过 API 密钥暴露 /me/password、/users 或 /users/* 等管理路由。
- 部分工具需要特定参数（如时区、websiteId）。
- 具体收费、价格、平台支持细节暂未提供。
