ObsidianCorps Umami Analytics

ObsidianCorps Umami MCP

询问有关自托管 Umami 分析数据的问题，无需将数据发送到其他分析 SaaS。

适用于 Umami Cloud 和自托管 Umami Analytics 的安全、适合模型使用的 Model Context Protocol 服务。它面向 Umami v3.3.1 和 2026-07-28 MCP 协议，同时保留与 2025 年前后 MCP 客户端的兼容性。

安装

要求：Node.js 20 或更新版本，并配置一种身份验证模式。

npx -y @obsidiancorps/umami-mcp

试着询问：

• “比较本月和上个月的网站流量。”
• “哪些来源带来了最多转化？”
• “查找 Web Vitals 表现不佳的页面。”

Agent 技能

此仓库还包含 Umami Analytics 技能。 MCP 服务提供对 Umami 的访问；该技能会指导 Agent 使用这些工具进行流量 比较、转化分析、收入分析和性能调查。 它遵循 Agent Skills 格式。

对于 MCP Market 的 从 GitHub 导入，请使用技能文件夹 URL：

https://github.com/ObsidianCorps/umami-mcp/tree/main/skills/umami-analytics

URL 必须指向包含 SKILL.md 的文件夹。对于公共仓库，请选择 公共仓库。必须先将该文件夹推送到 main，市场才能导入。

如需手动安装，请将 skills/umami-analytics 复制到 Agent 的技能目录 （例如，项目中的 .claude/skills/umami-analytics）。请单独配置并验证 MCP 服务；导入技能不会安装服务，也不会授予分析数据的访问权限。

此实现的优势

• 覆盖当前 Umami v3 功能：收入 API、会话回放、热图、事件/会话属性透视和类型化序列、细分、群组、看板、链接、像素、Web Vitals 报告，以及成熟的分析 API。
• 精简的模型接口：17 个只读工具围绕分析工作流组织 API，而非提供数十个几乎重复的端点工具。
• 适合模型使用的输入：自动解析网站名称/域名，自动选择一个可访问的网站，日期范围支持预设值或精确的 ISO/epoch 时间戳。
• 结构化 MCP 结果：每个工具都会声明输出架构，并返回 structuredContent 和可读 JSON。
• 安全的默认设置：默认不提供变更操作；破坏性工具需要额外启用，并要求提供与目标精确匹配的确认字符串。
• 两种现代传输方式：本地 stdio 和无状态 Streamable HTTP。不再提供旧版 HTTP+SSE。
• 纵深防御：响应字节数限制、请求超时、HTTPS 强制要求、令牌刷新、DNS 重绑定防护、精确的来源检查，以及恒定时间的 MCP bearer 验证。
• 支持云端和自托管身份验证：Umami Cloud API 密钥、预先签发的自托管令牌，或延迟执行的用户名/密码登录（包括 Umami v3.3+ 双因素验证），并在 401 后刷新一次。

配置

从源代码构建

要求：Node.js 20 或更新版本。

npm install
npm run build
UMAMI_API_KEY=your-key node dist/cli.js

MCP 客户端配置示例：

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "@obsidiancorps/umami-mcp"],
      "env": {
        "UMAMI_API_KEY": "your-key",
        "UMAMI_DEFAULT_WEBSITE_ID": "optional-website-uuid"
      }
    }
  }
}

对于源代码检出，请将命令替换为 node，并将参数替换为 dist/cli.js 的绝对路径。

身份验证

请准确选择一种模式：

模式	变量	API 基础地址
Umami Cloud	UMAMI_API_KEY	默认为 https://api.umami.is/v1
自托管令牌	UMAMI_BASE_URL、UMAMI_TOKEN	根 URL 后会添加 /api
自托管登录	UMAMI_BASE_URL、UMAMI_USERNAME、UMAMI_PASSWORD	根 URL 后会添加 /api
自托管登录 + 2FA	登录变量以及 UMAMI_TWO_FACTOR_SECRET	根 URL 后会添加 /api
一次性 2FA 登录	登录变量以及当前的六位数 UMAMI_TWO_FACTOR_CODE	根 URL 后会添加 /api

UMAMI_TWO_FACTOR_SECRET 是注册身份验证器时显示的 Base32 设置种子。MCP 会在需要时生成六位数的 SHA-1 TOTP，且绝不会记录或返回该验证码。由于同时存储密码和 TOTP 种子会破坏两种验证因素之间的隔离，请使用专用的最小权限 Umami 账户，并妥善保护其环境。预先签发的 UMAMI_TOKEN 无需保留这两种凭据。

UMAMI_TWO_FACTOR_CODE 仅作为一次性备用方案；它会很快过期，不适合用于常规 MCP 启动。请只配置一种双因素变量。

非本地的纯 HTTP Umami URL 会被拒绝。仅在明确可信的专用网络中，才设置 UMAMI_ALLOW_INSECURE_HTTP=true。

工具

默认的只读工具集如下：

工具	用途
umami_check_connection	验证身份验证并检查当前账户
umami_list_websites、umami_get_website	查找并检查网站
umami_get_overview、umami_get_metrics	汇总 KPI、序列和排名维度
umami_get_realtime	检查当前 30 分钟的活动窗口
umami_list_sessions、umami_inspect_session	浏览会话、活动、属性和回放元数据
umami_query_session_data	查询会话属性、数据透视、统计数据、每周流量和类型化序列
umami_list_events、umami_query_event_data	浏览事件、对比统计数据、序列、属性、值和数据透视
umami_get_revenue	获取收入统计数据、图表、维度和会话
umami_list_replays	列出回放或检索回放事件流
umami_run_report、umami_list_reports	运行或查找漏斗、旅程、目标、留存、归因、UTM、收入、性能、细分和热力图报告
umami_list_segments	查找细分和群组
umami_list_assets	查找看板、跟踪链接和像素

资源会公开 umami://capabilities 和实时的 umami://websites 列表。可复用提示词涵盖分析审查、转化审查和实时问题排查。

时间范围

大多数分析工具接受以下参数之一：

• period：last_24_hours、last_7_days、last_30_days、last_90_days、today、yesterday、this_week、last_week、this_month 或 last_month；或
• 同时提供 startAt 和 endAt，值为 Unix 纪元毫秒或带偏移量的 ISO 8601 时间戳。

日历周期遵循所提供的 IANA timezone。滚动周期会保留最近的数据，而不是将时间范围取整到午夜。

修改和破坏性操作

默认情况下不注册任何修改工具。

UMAMI_ENABLE_WRITE_TOOLS=true

这会添加用于创建／更新网站、细分、报告、看板／链接／像素以及发送分析事件的工具。如需额外开放永久重置／删除操作：

UMAMI_ENABLE_WRITE_TOOLS=true
UMAMI_ENABLE_DESTRUCTIVE_TOOLS=true

破坏性调用需要确认字符串，例如 RESET <website-id> 或 DELETE reports <report-id>。MCP 注解也会将这些工具标记为具有破坏性，以便支持这些注解的宿主要求用户批准。

Streamable HTTP

回环示例：

MCP_TRANSPORT=http MCP_BEARER_TOKEN=replace-me npm start
# MCP:    http://127.0.0.1:3000/mcp
# Health: http://127.0.0.1:3000/health

对于容器或非回环绑定，必须同时设置 MCP_BEARER_TOKEN 和 MCP_ALLOWED_HOSTS：

docker build -t umami-mcp .
docker run --rm -p 3000:3000 \
  -e UMAMI_API_KEY=your-key \
  -e MCP_BEARER_TOKEN=long-random-secret \
  -e MCP_ALLOWED_HOSTS=mcp.example.com \
  umami-mcp

如果基于浏览器的 MCP 客户端连接，请将 MCP_ALLOWED_ORIGINS 设置为以逗号分隔的精确浏览器来源列表。没有 Origin 标头的请求仍可供原生客户端使用。请在受信任的反向代理处终止 TLS；内置静态 bearer 验证适用于此边界之后的场景，不能替代面向公众的多用户服务所需的 OAuth。

配置参考

变量	默认值	说明
UMAMI_BASE_URL	用于 API 密钥验证的 Cloud API	Umami 根 URL 或完整的 API 基础 URL
UMAMI_DEFAULT_WEBSITE_ID	—	大多数调用无需解析站点
UMAMI_TIMEOUT_MS	15000	上游请求超时时间，100–120000 ms
UMAMI_MAX_RESPONSE_BYTES	512000	上游响应最大值，1 KB–10 MB
UMAMI_ENABLE_WRITE_TOOLS	false	注册非破坏性变更工具
UMAMI_ENABLE_DESTRUCTIVE_TOOLS	false	注册重置/删除工具；需要启用写入工具
MCP_TRANSPORT	stdio	stdio、http 或 streamable-http
MCP_HOST	127.0.0.1	HTTP 绑定地址
MCP_PORT	3000	HTTP 端口
MCP_BEARER_TOKEN	—	保护 HTTP MCP 端点
MCP_ALLOWED_HOSTS	—	用于非回环 HTTP 的逗号分隔主机名
MCP_ALLOWED_ORIGINS	—	逗号分隔的精确浏览器来源

开发

npm install
npm test
npm run typecheck
npm run lint
npm run format:check
npm run build
npm run check

测试会通过真实的内存、stdio 和 Streamable HTTP MCP 客户端驱动服务端。提交更改前，请参阅 CONTRIBUTING.md 和 SECURITY.md。

兼容性基线

• Umami：v3.3.1；预计兼容提供文档所述路由的 v3 后期版本。
• MCP SDK：TypeScript SDK v2.0.0。
• MCP 协议：2026-07-28，以及 SDK 面向 2025 年客户端的无状态兼容路径。
• Node.js：20、22 和 24。

Umami 是其各自所有者的商标。此独立集成与 Umami Software 无关联，也未获其认可。

许可证

Apache-2.0。请参阅 LICENSE。