umami-mcp

Umami MCP 服务

一个用于 Umami Analytics 的 模型上下文协议 服务。询问 Claude、Cursor 或任何 MCP 客户端有关流量的问题，还可以让它创建和管理网站，而凭据始终保留在你自己的设备上。

"Which pages drove the most visitors last month, and where did that traffic come from?"
"Build a funnel from /pricing to /signup to /welcome for the last 30 days."
"Add analytics for my new site blog.example.com and give me the tracking snippet."

_{这是一个临时网站，使用生成的流量，运行在实时 Umami 3.3.1 实例上，并由只读服务账号读取——因此计数很小且毫无实际意义，但每一条数据都是真实采集并真实查询的。使用 vhs demo/demo.tape 重新生成。}

为什么要开发这个项目

Umami 现在提供官方 MCP 服务（自 v3.4.0 起，MCP_ENABLED=1，端点为 /mcp）。如果你只需要只读分析数据，就使用它：它运行在 Umami 内部，因此无需额外部署任何内容。请参阅 Umami 文档。

本服务面向官方服务有意不提供的功能：

	官方（/mcp）	umami-mcp
读取分析数据和报告	是	是
创建和更新网站、团队、跟踪代码片段	—	write 模式
用户管理	—	admin 模式
删除网站 / 重置数据	—	仅在主动启用时可用
低于 Umami 3.4 的版本	—	3.x
登录	API 密钥	API 密钥、密码或 OAuth（多租户）

此外还有一些社区服务；如果你只想获得广泛的 API 覆盖，建议先看看 0xtlt/umami-mcp——它封装的 API 比本项目更多。一些较早的服务 （jakeyShakey、 mikusnuz、 mittwald、 Macawls）是基于 v2 API 编写的，在现代实例上无法正常工作，因为 v3 重命名了部分内容，却没有提供别名：

	Umami v2	Umami v3
热门页面	/metrics?type=url	/metrics?type=path
主机名	/metrics?type=host	/metrics?type=hostname
UTM 数据	/metrics?type=utm_source	POST /api/reports/utm
漏斗、留存、用户旅程、归因、收入	—	POST /api/reports/*

本服务专为解决其他服务无法做到的两件事而开发：

1. 完整且经过验证的 v3 报告覆盖。 所有七种 v3 报告类型——漏斗、留存、用户旅程、目标、收入、归因和 UTM——都在实时 Umami 3.3.1 实例上进行了测试。报告的请求格式很容易出错：日期应作为 ISO-8601 字符串放在 parameters 中，而不是放在 filters 中，也不是使用 API 其他部分采用的 Unix 时间戳毫秒值。归因接受 first-click / last-click，而不是你可能会猜到的驼峰拼写。

2. 采用能力模型，而不是布尔开关。 见下文。

安全模型

一个分析 MCP 服务持有的凭据可以读取你记录过的所有访客会话；如果你允许，还能将它们全部删除。设计由此而来。

你的凭据绝不会离开你的环境。 配置只从进程环境中读取。没有遥测、没有回连，也没有托管中继。此服务唯一会联系的主机就是你设置的 UMAMI_URL。如果你自行托管，任何分析数据都不会传给第三方——包括本软件的作者。

当心任何提供托管端点、让你将实例指向该端点的 Umami MCP。在 Umami 3.4 之前，自托管实例没有 API 密钥，因此所谓的“便利”托管意味着要把你的管理员密码发送到别人的服务器。在 3.4 及之后的版本中，若要使用这类服务，请从专用账户提供可撤销的 API 密钥，绝不要提供密码。

默认遵循最小权限原则。 服务以 read 模式启动。扩大权限需要有意为之：

模式	增加的权限
read （默认）	分析、报告、列出网站
write	创建和更新网站及团队
admin	用户管理
+ UMAMI_MCP_ALLOW_DESTRUCTIVE=true	删除网站、重置数据、删除用户

未开放的工具根本不会注册，因此也不会出现在模型的工具列表中。这一点与 READONLY=true 标志不同：从未公开的工具，不可能被提示词注入指令调用；这类指令可能藏在你自己的分析数据中，例如来源字符串或页面标题里。没有需要遗忘或绕过的运行时检查，因为根本不存在这个工具。

破坏性操作需要经过核实的明确确认。 umami_delete_website 接受 confirmDomain 参数，会获取实时记录，并且只有在两者匹配时才会执行。模型若误选了网站 UUID，得到的会是错误，而不是被清空的数据集。

凭据不会保存在客户端配置中。 无需将密码写入 ~/.claude.json 或 mcp.json，服务会从你控制的文件 ~/.config/umami-mcp/env 中读取密码；如果其他用户也能读取该文件，服务会发出警告。请参阅凭据。

输出中的秘密会被清除。 MCP 输出会传给模型，并且经常进入聊天记录，无法撤回。密码、Bearer 令牌和 JWT 会在每条错误和响应离开进程前被删去。

拒绝通过网络泄露凭据。 启动时会拒绝向远程主机使用明文 HTTP；仅允许在本地开发时连接 localhost。

安装

有三种运行方式。默认且推荐自行托管——托管实例的存在，是为了让你无需克隆任何内容，就能在两分钟内试用。

	运行位置	凭据存放位置	适用场景
托管版	asif.dev	封存在令牌中，绝不存储	试用；Claude 网页版和 Cowork
源码版	你的计算机	只有你能读取的文件	在 Claude Code 中日常使用
Docker	你的服务器	你的 .env	团队、持续运行

如果你选择自行托管，并想在 Claude 网页版中使用，请在自己的域名后运行并启用 UMAMI_MCP_OAUTH=true——这样你的任何数据都不会经过别人的基础设施。

1. 使用托管实例（无需安装）

在 Claude 中添加自定义连接器，并将其指向：

https://umami-mcp.asif.dev/mcp

系统会在授权页面上要求你填写自己的 Umami URL 和登录信息。有关凭据的处理方式，请参阅 Claude 网页版、Cowork 和网页版 Claude Code。

2. 从源码运行

git clone https://github.com/Asif2BD/umami-mcp.git
cd umami-mcp
npm install && npm run build

然后设置凭据，并将其注册到客户端：

claude mcp add umami --scope user -- node "$PWD/dist/index.js"

需要 Node 20 或更高版本。

3. Docker

git clone https://github.com/Asif2BD/umami-mcp.git
cd umami-mcp
cp .env.example .env    # then edit .env
docker compose up -d

npm： 尚未发布。发布后，npx -y @asif2bd/umami-mcp 将取代上述克隆并构建的步骤。在此之前，请使用源码版或 Docker。

凭据

在 Umami 3.4.0 或更高版本中，优先在 UMAMI_API_KEY 中使用 API 密钥（Settings → API keys）：它可以单独撤销，无需更改密码。发送到自托管实例时，它会作为 Authorization: Bearer 发送；发送到 Umami Cloud 时则作为 x-umami-api-key 发送。较旧的实例没有 API 密钥，因此凭据是真实的账户密码。无论哪种情况，MCP 客户端通常都要求将其嵌入配置 JSON 中，例如 ~/.claude.json、mcp.json 等文件。这些文件通常可被广泛读取，可能会被粘贴到问题帖和屏幕共享中，还可能由某些客户端在设备间同步。

因此，此服务改为从你控制的文件中读取凭据。只需创建一次：

mkdir -p ~/.config/umami-mcp
cat > ~/.config/umami-mcp/env <<'EOF'
UMAMI_URL=https://analytics.example.com
UMAMI_USERNAME=mcp-bot
UMAMI_PASSWORD=your-password
UMAMI_MCP_MODE=read
EOF
chmod 600 ~/.config/umami-mcp/env

服务会自动加载该文件。如果其他用户也能读取该文件，启动时会发出警告。

查找顺序——以找到的第一个文件为准；真实环境变量始终优先于文件中的设置，因此你仍可在需要时通过客户端配置传入设置：

1. 如果已设置，则使用 $UMAMI_MCP_ENV_FILE
2. ~/.config/umami-mcp/env（或 $XDG_CONFIG_HOME/umami-mcp/env）
3. 工作目录中的 ./.env

连接客户端

Claude Code

使用上面的凭据文件，注册信息中完全不包含机密：

claude mcp add umami --scope user -- node ~/umami-mcp/dist/index.js

请使用检出目录的绝对路径。如果 Node 位于 nvm 目录下，也请提供解释器的完整路径，因为 MCP 客户端不会加载你的 shell 配置文件：

claude mcp add umami --scope user -- ~/.nvm/versions/node/v22.22.0/bin/node ~/umami-mcp/dist/index.js

Claude Desktop / Cursor / VS Code

{
  "mcpServers": {
    "umami": {
      "command": "node",
      "args": ["/absolute/path/to/umami-mcp/dist/index.js"]
    }
  }
}

如果你更愿意将所有内容放在一处，仍可使用环境变量；环境变量的优先级高于文件中的设置：

{
  "mcpServers": {
    "umami": {
      "command": "node",
      "args": ["/absolute/path/to/umami-mcp/dist/index.js"],
      "env": {
        "UMAMI_URL": "https://analytics.example.com",
        "UMAMI_USERNAME": "mcp-bot",
        "UMAMI_PASSWORD": "your-password"
      }
    }
  }
}

检查是否正常工作

让客户端运行 umami_whoami。它会报告实例、账户和权限模式——这是确认连接并查看服务获准执行哪些操作的最快方式：

{
  "instance": "https://analytics.example.com",
  "authenticatedAs": "mcp-bot",
  "role": "admin",
  "serverMode": "read",
  "destructiveOperations": "disabled"
}

然后试试：“列出我的 Umami 网站”，或“上周访问量最高的页面是什么？”

Claude 网页版、Cowork 和网页版 Claude Code

这些客户端无法启动本地进程，因此需要一个公开的 HTTPS MCP 服务；而且它们的连接器界面只接受 OAuth，没有填写静态承载令牌或自定义请求头的字段。

如果按最直接的方式托管，将一组 Umami 凭据写入服务且不设置身份验证，就会让该 URL 成为访问对应 Umami 的开放代理。因此，此服务改用 OAuth，并且不会将自身变成凭据存储库。

使用托管实例

在 Claude 中添加自定义连接器，并使用此 URL：

https://umami-mcp.asif.dev/mcp

Claude 会自行完成注册，将你带到授权页面，并要求提供你自己的 Umami URL、用户名和密码。主机上的其他用户不会共享这些信息。

自行托管

UMAMI_MCP_OAUTH=true
UMAMI_MCP_TRANSPORT=http
UMAMI_MCP_ISSUER=https://mcp.example.com      # public HTTPS URL of this server
UMAMI_MCP_TOKEN_KEY=<32 random bytes>          # keep stable; see below
UMAMI_MCP_TOKEN_TTL=2592000                    # 30 days

生成密钥后请妥善保管：

node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

同时设置 UMAMI_URL，即可将所有用户固定到同一实例，而不是让他们自行选择。

凭据的处理方式

授权页面会根据用户指定的 Umami 实例验证凭据，然后使用 AES-256-GCM 将凭据封装进访问令牌。服务不维护会话表，也不存储任何凭据：每次请求都会解密令牌，创建一个仅限该用户使用的 MCP 服务，处理调用后将其丢弃。

坦诚地说，取舍在于：任何持有 UMAMI_MCP_TOKEN_KEY 的人都可以解密其获取的任何令牌。请将其视为部署中最敏感的值。轮换此密钥会使所有已签发的令牌失效，这正是控制影响范围的预期措施。

无论用户选择何种权限，破坏性工具绝不会通过 OAuth 暴露。它们的输入确认防护假定本地操作者能够看到自己即将删除的内容，而远程调用者无法看到这些内容。

作为普通 HTTP 服务运行

设置 UMAMI_MCP_TRANSPORT=http，并且不设置 UMAMI_MCP_OAUTH，即可在 /mcp 提供单租户端点，并提供 /health。

**在此模式下，服务本身没有身份验证机制。**任何能够访问该端口的人都可以使用你的 Umami 凭据。请将其限制在回环地址上，并通过隧道访问：

ssh -N -L 3334:127.0.0.1:3334 you@your-server
claude mcp add --transport http umami http://127.0.0.1:3334/mcp

如果服务绑定到回环地址以外的地址，启动时会发出警告。

工具

工具	要求	描述
umami_list_websites	read	列出此 Umami 实例跟踪的网站及其 UUID
umami_get_website	read	按 UUID 获取单个网站的信息，包括其域名、所有者和创建日期。
umami_create_website	write	注册一个新网站以进行跟踪，并返回其 UUID。该 UUID 是 Umami 跟踪脚本的 data-website-id 属性值。
umami_update_website	write	更改网站名称、域名或共享标识
umami_reset_website	destructive	永久删除某个网站收集的所有分析数据，但保留网站本身
umami_delete_website	destructive	永久删除某个网站及其记录过的所有事件
umami_get_tracking_snippet	read	返回可直接粘贴的 HTML 脚本标签，用于将数据发送到此 Umami 实例中指定的网站。
umami_get_stats	read	某个网站在一段时间内的关键总计：页面浏览量、访客数、访问次数、跳出次数和网站总停留时间
umami_get_pageviews	read	按时间分段统计的页面浏览量和会话数，用于绘制流量图表
umami_get_metrics	read	按访客数排序的某个维度的热门值——热门页面、引荐来源、国家/地区、浏览器等
umami_get_active_visitors	read	过去几分钟内在网站上活跃的访客数
umami_get_realtime	read	当前活动的实时快照：包含国家/地区、URL、浏览器和设备信息的近期事件，以及按国家/地区、URL 和引荐来源汇总的数据
umami_get_event_stats	read	一段时间内自定义跟踪事件的总计：事件数、唯一事件名称数、访客数和访问次数，并与前一时段进行比较。
umami_list_sessions	read	单个访客的会话信息，包括浏览器、操作系统、设备、国家/地区和区域
umami_get_session_activity	read	某个访客会话中按顺序排列的页面浏览和事件，即访客在网站上的访问路径。
umami_report_utm	read	按 UTM 参数细分流量：来源、媒介、广告系列、关键词和内容
umami_report_funnel	read	分步骤展示转化漏斗
umami_report_retention	read	群组留存情况：某天首次访问的访客中，有多少人在之后的每一天再次访问。
umami_report_journey	read	访客在网站上最常见的有序访问路径，以页面序列表示，并列出每条路径的次数。
umami_report_goal	read	单个目标的进展：访问某个路径或触发某个自定义事件的访客数。
umami_report_revenue	read	携带收入属性的事件所产生的收入随时间的变化，并按国家/地区、区域、引荐来源和渠道细分
umami_report_attribution	read	根据首次点击或末次点击模型，将转化归因于引流渠道——引荐来源、付费广告和 UTM 参数。
umami_list_users	admin	列出 Umami 用户账户及其角色
umami_create_user	admin	创建 Umami 用户账户
umami_delete_user	destructive	永久删除某个用户账户及其拥有的网站
umami_list_teams	read	列出团队及其成员。
umami_create_team	write	创建团队，以便在用户之间共享网站。
umami_whoami	read	验证此 MCP 服务是否能够访问配置的 Umami 实例，并报告其认证所用的账户以及服务正在运行的权限模式

时间范围

每个分析工具都接受 period 简写——24h、7d、30d、12m、today、yesterday——以代替 epoch 毫秒时间戳。模型通常能可靠理解“过去 30 天”，但不擅长时间戳运算；而计算错误的 epoch 会在不报错的情况下返回错误时间范围的数据。仍可使用 epoch 毫秒格式的显式 startAt/endAt，并且它们具有更高优先级。

配置

所有选项请参阅 .env.example。核心选项如下：

变量	默认值	用途
UMAMI_URL	必填	你的 Umami 实例
UMAMI_USERNAME / UMAMI_PASSWORD		自托管登录凭据
UMAMI_API_KEY		使用 API 密钥代替登录（Umami Cloud 或自托管 3.4.0+）
UMAMI_MCP_MODE	read	read / write / admin
UMAMI_MCP_ALLOW_DESTRUCTIVE	false	解锁删除和重置操作
UMAMI_MCP_TRANSPORT	stdio	stdio 或 http
UMAMI_MCP_HOST	127.0.0.1	HTTP 绑定地址
UMAMI_MCP_PORT	3334	HTTP 端口
UMAMI_MCP_ENV_FILE		凭据文件的显式路径

推荐设置

为 MCP 服务创建一个专用的 Umami 账户，而不是重复使用管理员登录账号，并且只授予它所需的网站权限。这样一来，即使凭据泄露，影响范围也仅限于一个可以删除的机器人账户，而不是你的管理员账户。

兼容性

已针对 Umami 3.3.1 验证，并在生产环境中通过 3.4.1（自托管、PostgreSQL）运行。 Umami Cloud 可通过 UMAMI_API_KEY 使用；自托管 3.4.0+ 也支持此方式。 不支持 Umami v2：由于上述指标类型已重命名，v2 和 v3 需要不同的客户端，而本项目面向 v3。

开发

npm install
npm run build
npm test          # unit tests, no network required

test/e2e.mjs 和 test/write-e2e.mjs 会通过真实 MCP 客户端，针对在线实例运行已构建的服务。写入测试会在 .invalid 域名下创建一个临时网站，然后将其删除；请将其指向非生产实例。

贡献

欢迎提交问题和拉取请求。Umami v3 提供了约 127 个 API 路由，本服务涵盖了其中最实用的一些——会话回放、热图、像素、链接跟踪、看板和细分功能仍未映射。如果你添加工具，请如实设置级别和 destructive 标志，因为整个安全模型都依赖于它们。

如果 Umami 团队有意采用、分叉或将本项目上游合并，请提交一个问题——这正是本项目的初衷。

许可证

MIT © M Asif Rahman