Umami Compass

Umami Compass

适用于 Umami Analytics 的开源 MCP 服务——支持云端和自托管。

分发渠道：umami-compass on npm · 官方 MCP Registry 中的 io.github.webcredo/umami-compass

Umami Compass 是一个安全、只读的 Model Context Protocol 服务，适用于 Umami Analytics。它为 MCP 客户端提供准确的 Umami 3.2 分析数据，且不会暴露数据库或允许任意网络请求。

当前源代码版本为 0.5.1。与较旧的 Umami 版本搭配使用前，请参阅兼容性。

npx 示例使用稳定的 npm 发布渠道，并在每次 MCP 进程启动时检查该渠道。若要基于源代码进行评估，请克隆此仓库，运行 pnpm install --frozen-lockfile && pnpm build，并将 node /absolute/path/to/umami-compass/dist/cli.js 用作 MCP 命令。

为什么要做这个项目

现有的 Umami MCP 服务各自只覆盖了部分需求，但我们在 2026 年 7 月的审查中发现，它们在 Umami 3.2 响应准确性、Cloud 身份验证、安全边界或可扩展性方面存在不足。Umami Compass 设定了更高且可测试的质量标准：

• 两种产品均支持正确的身份验证：Umami Cloud 使用 x-umami-api-key，自托管实例使用 Bearer／登录身份验证。
• 支持 Umami 3.2 响应，包括 pageviews 和 sessions、Core Web Vitals、漏斗、用户旅程、归因、留存、收入、有界热力图和回放元数据。
• 从设计上确保只读：每个工具都声明 MCP 安全注解；不提供创建、更新、删除、原始 HTML 或任意 URL 工具。
• 纵深防御：固定上游源站、HTTPS 策略、网站和团队允许列表、范围／页面／响应字节数上限、请求超时、取消传播和错误脱敏。
• 提供可用于决策的洞察：有界的流量与性能组合概览、流量变化证据、发布影响分析、跟踪健康状况审计，以及无需任意 API 访问即可解析网站。
• 为 Agent 提供友好的输出：机器可读的 structuredContent、通用状态／范围／截断封装、两个资源和六个引导式提示词。
• 对贡献者友好的架构：端点模块、依赖注入式 HTTP、集中式访问策略、ADR 和真实 MCP 集成测试。

有关证据和方法，请参阅带日期的生态审查。

快速开始

要求：Node.js 22 或更高版本，以及尽可能仅具备查看权限的 Umami 身份。

示例使用自动更新的稳定版启动器：

npx --yes --prefer-online umami-compass@latest

@latest 会选择稳定的 npm 渠道，而 --prefer-online 会让 npm 即使在包元数据已缓存时也检查注册表。如果缓存中已有完全相同的版本，npm 仍会复用缓存包。更新会在 MCP 进程下次启动时生效；已运行的本地服务无法自行替换。

若要选择预览版，请改用 umami-compass@next。对于需要可复现的 CI 或集中管理的环境，请固定到确切版本并省略在线检查，例如 npx --yes [email protected]。无人值守的生产环境中，切勿使用预览渠道。

Umami Cloud

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["--yes", "--prefer-online", "umami-compass@latest"],
      "env": {
        "UMAMI_API_KEY": "replace-with-your-api-key"
      }
    }
  }
}

设置 UMAMI_API_KEY 且不设置 URL 时，API 根地址默认为 https://api.umami.is/v1。

自托管 Umami

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["--yes", "--prefer-online", "umami-compass@latest"],
      "env": {
        "UMAMI_URL": "https://analytics.example.com",
        "UMAMI_USERNAME": "mcp-viewer",
        "UMAMI_PASSWORD": "replace-me",
        "UMAMI_WEBSITE_IDS": "6b2c8c10-908c-4a8e-a924-4049eb3bde8c"
      }
    }
  }
}

UMAMI_URL 是实例的来源地址；系统会在其后追加 /api。如果反向代理公开了自定义的精确 API 根地址，请改用 UMAMI_API_URL。

UMAMI_WEBSITE_IDS 是可选的安全允许列表，不是凭据。将示例 UUID 替换为来自 Umami（或 list_websites）的网站 ID；多个 ID 用逗号分隔；也可以移除此变量，以发现通过直接访问或团队成员身份可见的所有网站。

UMAMI_TEAM_IDS 是用于发现以及直接访问网站和报告的严格团队边界。设置该变量后，没有所选团队 ID 的用户自有网站将被排除。如果同时设置了 UMAMI_WEBSITE_IDS，网站必须同时通过这两个允许列表的检查。

不要提交真实凭据。如果条件允许，请优先使用专用的只读 Umami 帐户和客户端／操作系统的机密存储。

工具

默认采用最小权限配置，启用 core,insights：八个基础聚合工具，以及七个可直接用于决策的聚合工作流。按行级别展示的事件、会话、回放、热图和其他更敏感的模块仍需选择启用。

工具集	工具	默认启用
core	get_server_info, list_websites, get_website, get_website_stats, get_pageviews, get_metrics, get_active_visitors, get_website_date_range	是
insights	resolve_website, get_portfolio_overview, analyze_performance_portfolio, explain_traffic_change, compare_traffic_series, analyze_release_impact, tracking_health_check	是
events	list_events, get_event_stats, get_event_series	否
sessions	list_sessions, get_session_stats, get_session, get_session_activity	否
performance	get_web_vitals, get_performance_breakdown, compare_web_vitals, compare_performance_breakdown, get_performance_cross_tab, get_route_group_performance	否
reports	已保存的报告和细分，以及目标、漏斗、用户旅程、留存、UTM、归因和多字段细分报告	否
revenue	get_revenue_stats, get_revenue_metrics	否
replay	list_replays（仅元数据；绝不返回原始 rrweb 负载）	否
heatmaps	get_heatmap（点击/滚动页面和有界详细点位）	否

设置 UMAMI_TOOLSETS=all 或以逗号分隔的子集。默认配置包含 15 个聚合工具；all 包含 42 个。多网站洞察最多涵盖 50 个网站，并发处理的网站工作线程为 4 个。高基数报告、性能、热图、渠道扇出和活动结果均带有明确的限制和截断元数据。

对于页面、页面标题、设备和浏览器排名，get_performance_breakdown 默认要求每行至少包含 20 个性能事件。这是用于探索性 p75 的质量保护措施，并不代表统计显著性。Umami 3.2 使用 count(*) 而非 count(metric) 计算这些计数，因此 Compass 会将其标记为事件数，绝不会将其呈现为特定指标的样本数。显式设置 minimumSampleCount 可提高保护门槛，或将其降低为 1，以纳入所有其他条件均有效的行。

在 Compass 应用样本保护门槛之前，Umami 3.2 会将页面、页面标题和浏览器候选项限制为 500 个。因此，细分响应会报告实际生效的最低门槛、排除行数、候选项覆盖率，以及上游限制是否可能导致筛选后的排名不完整。如果所有完整候选项的样本量都不足，emptyReason 为 insufficient_sample_size；如果候选项数量限制导致无法得出该结论，dataStatus 则为 unknown。

成功的工具响应会保留现有的 data 字段，并添加通用的 meta 信封。根据请求内容，其中包含 dataStatus、emptyReason、websiteId、requestedRange 和 timezone。截断分为两类：responseTruncated 表示主要结果不完整，sectionsTruncated 表示有界嵌套部分被截断；聚合字段 truncated 则继续保留以确保兼容性。

服务会公开 umami://websites 和经过清理的 umami://capabilities 资源。网站发现只返回 id、name 和 domain；需要详细元数据时，请显式请求 get_website。get_server_info 会以工具的形式返回相同的本地版本、已启用的工具集、限制和功能标记。引导式提示词涵盖分析报告、每周全局概览简报、流量调查、发布影响、追踪健康状况和转化审核；仅当所需工具集已启用时，才会注册相应提示词。安排定期简报仍由 MCP 客户端负责；本地 stdio 服务不会运行后台计划任务，也不会发送消息。

性能分析与上游限制

analyze_performance_portfolio 会针对每个选定网站执行两个有界性能请求和两个汇总流量请求，并发数为 4 个网站。verbosity="compact"（默认值）会返回决策摘要；standard 会增加简洁的单站点行和特定指标的下钻数据；full 会返回完整的标准化单站点依据。下钻网站仅由 detailMetric 选择。每次页面浏览的性能事件数以比率形式返回，该值可能大于 1。实际采集覆盖率仍为 unknown_upstream，因为 Umami 不会返回去重后的已覆盖页面浏览数。各网站的 p75 值会排序，但绝不会取平均，因为不同网站的百分位数无法合并。

compare_web_vitals 会比较全部 5 个汇总指标。compare_performance_breakdown 会对齐页面、标题、设备或浏览器行，优先返回可比较的行，默认排除低于 minimumSampleCount 的行；如果上游前 500 项列表已达上限，导致候选项缺失情况不确定，则会省略这些候选项。设置 includeInsufficient=true 可在有用的比较结果之后附加样本量不足的行。get_performance_cross_tab 最多通过 10 个经过筛选的扇出请求推导组合，并报告候选项来自性能事件还是流量指标。get_route_group_performance 接受调用方定义的路径正则表达式，并直接查询每个路由组；路由组可能重叠，PostgreSQL 和 ClickHouse 的正则表达式方言细节也可能不同。

性能工具仅接受与 Umami 支持的数据库后端一致的页面／标题筛选条件和已持久化环境筛选条件。excludeBounce、引荐来源、UTM、主机名、查询、事件、标签及其他未持久化的性能字段会被拒绝，而不会被忽略。特别是，Umami 3.2 会构建其性能报告中的 excludeBounce 联接，但不会使用它。

Umami 3.2 不会返回特定指标的样本数，也不会返回图表数据点中的计数。因此，如果图表数据点缺少该字段，Compass 会返回 count: null，设置 sampleCounts.status="unavailable_upstream"，并将不完整的所请求／当前时间段标记为 partial: true。总体计数命名为 performanceEventCount。非 CLS 指标中所有百分位数均为零的占位值会被视为不可用；零 CLS 则仍是有效值。

由于 Umami 的汇总性能报告不会采集或公开这些数据，LCP 分解、LCP 元素／资源归因、缓存状态和边缘区域均会明确报告为不可用。Compass 不会通过相减无关的汇总百分位数来推断分解结果。

筛选条件、直接流量、渠道和流量质量

纯字符串筛选条件仍保持兼容。结构化筛选条件新增了 equals、not_equals、contains、not_contains、regex、not_regex、is_empty 和 is_not_empty。相等运算符接受数组，以支持原生 IN 或 NOT IN 行为：

{
  "filters": {
    "referrer": { "operator": "is_empty" },
    "path": { "operator": "not_equals", "value": ["/admin", "/internal"] }
  }
}

为保持兼容，{"referrer": ""} 也会筛选出引荐域名为空的行。这与 Umami 的 direct 渠道并不总是相同：带有营销活动参数的无引荐来源访问，可能会被归类为联盟、邮件、付费或其他渠道。若需精确匹配 Umami 的渠道归因，请使用 filters.channel: "direct"。对于结构化筛选和引荐来源为空的筛选，Compass 使用 Umami 中性引荐域名列，以免 Umami 对外部引荐来源的处理错误地移除内部流量或无引荐来源流量。

explain_traffic_change、analyze_release_impact 和 run_breakdown_report 均接受 filters.channel，包括 direct。run_breakdown_report 还接受将 channel 作为字段，因此可以处理 channel × device 之类的请求。Umami 3.2 原生不支持将渠道用作筛选条件或细分字段；Compass 通过有界的扩展指标扇出计算这些结果，并在 dataQuality 中报告候选覆盖率、遗漏行数、请求数和截断情况。渠道交叉表不能与自定义事件或 filters.match: "any" 搭配使用，因为 Umami 无法在该 OR 分组之外表达所需的候选谓词；Compass 会拒绝这些请求，而不是返回重叠总数。

流量变化、版本发布影响、对比序列和细分结果会结合生成式域名、极高的跳出率、接近零的访问时长以及最低流量等特征，保守地标记疑似引荐垃圾流量。将 trafficSegment 设为 human，可通过原生否定筛选条件，仅从流量结果中排除这些候选项。如果无法评估两个时段，或 filters.match: "any" 会弱化必要的排除条件，该预设将采取失败关闭策略。相关发现属于启发式判断，并非确定的机器人分类，且会附带依据和阈值。无法将引荐来源排除条件应用于 Umami 3.2 性能事件；版本发布影响分析会将此类性能证据标记为 scope_mismatch，而不会悄悄改用不同受众进行比较。

analyze_release_impact 默认返回精简的执行摘要、精确的对比时段和建议检查项，同时避免细分扇出；将 detailLevel 设为 full，可获取细分、流量质量证据和完整的 Web Vital 变化。通过 otherReleases 传入已知的相邻部署，以便 Compass 将结果标记为受混杂因素影响，而不是将整个时段的变化都归因于某个版本发布。当 Web Vital 样本不足时，主要判定为 insufficient_data，而 sampleReadiness 会报告流量和性能方面的不足、预计的 recheckAt，以及在观测到的速率允许时采用的更长等长时段。

compare_traffic_series 会根据请求的时区，将稀疏行补齐至实际时间桶，包括夏令时转换。如果当前时段和对比时段的本地时间桶数量不同，则会返回原始序列，并将 alignedChangesAvailable: false；不会给出派生的时间桶变化值，也不会移动对比数据。

结构化筛选条件仍遵循字段专属的长度限制；每个条件最多 20 个值，每个请求最多 30 个条件、100 个值，序列化查询总大小上限为 16 KiB。

配置

必须且只能选择一种身份验证模式。

身份验证

• UMAMI_API_KEY — Umami Cloud/客户端 API 密钥。仅通过 x-umami-api-key 发送。
• UMAMI_ACCESS_TOKEN — 现有 Bearer 令牌。
• UMAMI_USERNAME + UMAMI_PASSWORD — 按需登录可自托管实例，并缓存令牌；遇到 401 时刷新一次。

身份验证变量没有默认值。请仅配置上述三种模式中的一种。

端点与访问范围

• UMAMI_URL — 自托管实例的源地址；会追加 /api。使用 API 密钥进行身份验证且未设置 URL 时，默认使用 Umami Cloud API 根地址。
• UMAMI_API_URL — 精确的 API 根地址；会取代 UMAMI_URL。无默认值。
• UMAMI_WEBSITE_IDS — 以逗号分隔的网站 UUID 允许列表。默认包括可直接访问或通过团队成员身份访问的所有网站。
• UMAMI_TEAM_IDS — 以逗号分隔的严格团队 UUID 允许列表，用于发现和直接访问网站/报告；最多 25 个 ID。设置此项后会排除用户拥有的网站；若同时配置 UMAMI_WEBSITE_IDS，两者取交集。
• UMAMI_TOOLSETS — 以逗号分隔的工具集，或 all。可用值为 core、insights、events、sessions、performance、reports、revenue、replay 和 heatmaps。默认值为 core,insights。

安全限制

• UMAMI_REQUEST_TIMEOUT_MS — 每个请求的超时时间，范围为 1,000 至 120,000 ms。默认值为 30000。
• UMAMI_MAX_RANGE_DAYS — 分析数据的最大时间范围，范围为 1 至 3,650 天。默认值为 366。
• UMAMI_MAX_RESPONSE_BYTES — 上游 JSON 响应体解码后的最大大小，范围为 102,400 至 52,428,800 字节。默认值为 10485760。
• UMAMI_ALLOW_INSECURE_HTTP — 设为 true 时允许使用非回环 HTTP。默认值为 false。

默认情况下必须使用 HTTPS。仅当主机为 localhost、127.0.0.1 或 ::1 时，才会自动接受纯 HTTP。

客户端配置

以下示例均使用 Umami Cloud。请在启动客户端的环境中导出密钥：

export UMAMI_API_KEY="replace-with-your-api-key"

对于自托管 Umami，请将 UMAMI_API_KEY 替换为自托管 Umami中所示的变量。只有当账号拥有对应的 Umami 区块权限且需要使用可选数据界面时，才添加 UMAMI_TOOLSETS=all。

Codex CLI、IDE 扩展和 ChatGPT 桌面版

同一主机上的 Codex 客户端和 ChatGPT 桌面版共用 ~/.codex/config.toml。env_vars 会转发密钥，而不会将其值写入配置：

[mcp_servers.umami-compass]
command = "npx"
args = ["--yes", "--prefer-online", "umami-compass@latest"]
env_vars = ["UMAMI_API_KEY"]

运行 codex mcp list 或 /mcp 进行验证。在 Codex IDE 扩展或 ChatGPT 桌面版中，也可以打开 MCP 服务器，添加一个命令为 npx --yes --prefer-online umami-compass@latest 的 STDIO 服务器，然后重启客户端。请参阅官方 Codex 和 ChatGPT MCP 指南。

ChatGPT 网页版不会读取本地 Codex 配置。当前软件包使用本地 stdio；托管插件需要未来支持经过身份验证的远程传输。

Claude Code

使用用户级别，将个人服务器配置保留在仓库之外：

claude mcp add --scope user --transport stdio \
  --env UMAMI_API_KEY="$UMAMI_API_KEY" \
  umami-compass -- npx --yes --prefer-online umami-compass@latest

使用 claude mcp list 或 /mcp 验证。对于适合团队共享的 .mcp.json，Claude Code 支持展开 ${UMAMI_API_KEY}；切勿提交实际值。请参阅官方 Claude Code MCP 指南。

Claude Desktop

打开 设置 → 开发者 → 编辑配置。在 macOS 上，文件路径为 ~/Library/Application Support/Claude/claude_desktop_config.json；在 Windows 上，路径为 %APPDATA%\Claude\claude_desktop_config.json。

{
  "mcpServers": {
    "umami-compass": {
      "command": "npx",
      "args": ["--yes", "--prefer-online", "umami-compass@latest"],
      "env": {
        "UMAMI_API_KEY": "replace-with-your-api-key"
      }
    }
  }
}

由于此客户端格式会存储密钥值，请妥善保护配置文件，然后完全退出并重启 Claude Desktop。请参阅官方本地 MCP 服务指南。

Cursor

将以下内容放入私有的全局文件 ~/.cursor/mcp.json；只有在 .cursor/mcp.json 不包含真实凭据时，才将其用于共享配置：

{
  "mcpServers": {
    "umami-compass": {
      "command": "npx",
      "args": ["--yes", "--prefer-online", "umami-compass@latest"],
      "env": {
        "UMAMI_API_KEY": "replace-with-your-api-key"
      }
    }
  }
}

在 Cursor 设置 → MCP 中启用服务器。请参阅官方 Cursor MCP 文档。

VS Code / GitHub Copilot

个人配置请使用 MCP: 打开用户配置，共享命令请使用 .vscode/mcp.json。VS Code 使用 servers（而非 mcpServers），并可提示输入经过遮蔽的密钥：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "umami-api-key",
      "description": "Umami API key",
      "password": true
    }
  ],
  "servers": {
    "umami-compass": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "--prefer-online", "umami-compass@latest"],
      "env": {
        "UMAMI_API_KEY": "${input:umami-api-key}"
      }
    }
  }
}

运行 MCP: 列出服务器以启动、检查或排查问题。请参阅官方 VS Code MCP 指南。

Gemini CLI

将以下内容添加到用户级 ~/.gemini/settings.json（或项目级 .gemini/settings.json）。Gemini 会展开 env 中的 shell 变量：

{
  "mcpServers": {
    "umami-compass": {
      "command": "npx",
      "args": ["--yes", "--prefer-online", "umami-compass@latest"],
      "env": {
        "UMAMI_API_KEY": "$UMAMI_API_KEY"
      },
      "trust": false
    }
  }
}

使用 gemini mcp list 或 /mcp 验证。参见官方 Gemini CLI MCP 指南。

故障排查

• 首先运行 npx --yes --prefer-online umami-compass@latest --version；需要 Node.js 22+。
• 更新软件包后，重启 MCP 服务，以便客户端请求新的工具列表。客户端仍显示旧列表或空列表时，可能还需要清除其缓存的工具。
• 401 表示凭据或身份验证模式有误；403 可能表示 Umami 账户没有访问该网站部分内容的权限。
• 对于可自托管的本地开发环境，允许使用 http://localhost:3000。其他纯 HTTP 来源需要明确启用不安全选项。
• 从默认工具集开始。仅在需要时启用 performance、reports、revenue、replay 或 heatmaps。
• 仅当客户端需要行级数据，且 Umami 身份允许公开这些数据时，才启用 events 或 sessions。

架构

flowchart LR
  Client["MCP client"] -->|stdio / JSON-RPC| Server["MCP server"]
  Server --> Policy["Module + access policy"]
  Policy --> Modules["Core / Events / Sessions / Performance / Reports / Revenue / Replay / Heatmaps"]
  Modules --> API["Typed, fixed-origin Umami client"]
  API -->|"API key / Bearer / lazy login"| Umami["Umami Cloud or self-hosted 3.2+"]

该软件包有意优先提供 stdio。公开的 HTTP 传输需要 OAuth 2.1、租户隔离、速率限制和运营威胁模型；绑定未经身份验证的端点会削弱项目的安全性。

未来可能会加入管理工具，但不能让它们意外进入只读构建。每个模块都会声明 access: "read" | "write"，服务器会在默认策略下拒绝写入模块。参见架构和 ADR-0001。

参见 Umami 3.2 API 覆盖矩阵，了解已实现、明确排除和后续优先处理的内容。

开发

corepack enable
pnpm install --frozen-lockfile
pnpm check
pnpm dev

要添加端点，请遵循添加工具。有关项目要求和拉取请求，请参见 CONTRIBUTING.md。

兼容性

• Umami 3.2.x 是参考实现和测试目标。
• 较旧的 Umami 版本可能仍适用于未更改的端点，但目前不作保证。
• CI 中会测试 Node.js 22、24 和 26。
• 截至 2026 年 7 月，MCP SDK v1 是稳定的生产版本，因此项目使用该版本；v2 分支仍处于预发布阶段。

安全与隐私

分析数据、会话元数据、收入数据和回放元数据可能包含敏感信息。请使用权限最小化的凭据、允许列表、最小工具集和较短的时间范围。生产环境使用前，请阅读 SECURITY.md。

Umami Compass 是一个独立的社区项目，与 Umami Software 无关联。

支持项目

Umami Compass 免费且开源。如果它为你节省了时间或改善了你的分析工作流，可以在 Ko-fi 上请我喝杯咖啡，以支持项目。

许可证

MIT © 2026 webcredo 和 Umami Compass 贡献者。