Umami MCP Server

一个用于 Umami Analytics 的 Model Context Protocol 服务器。向 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 没有官方的 MCP 服务器。社区已有几个实现，如果你只想要广泛的 API 覆盖，应该先看 0xtlt/umami-mcp——它封装的 API 比本服务器更多。一些较老的服务器（jakeyShakey、mikusnuz、mittwald、Macawls）是针对 v2 API 编写的，在现代实例上会失效，因为 v3 对名称做了修改，但没有提供别名：

这个服务器存在的意义，是完成其他服务器没有做到的两件事：

1. 完整且经过验证的 v3 报告覆盖。 全部七种 v3 报告类型——漏斗、留存、旅程、目标、收入、归因和 UTM——都在一个真实的 Umami 3.3.1 实例上进行了验证。报告封装很容易出错：日期应作为 ISO-8601 字符串放在 parameters 中，而不是放在 filters 中，也不是 API 其他地方使用的纪元毫秒。归因参数是 first-click / last-click，而不是你可能会猜到的驼峰式拼写。

2. 能力模型，而非布尔开关。 见下文。

Related MCP server: Umami MCP Server

安全模型

一个分析类 MCP 服务器持有可以读取你记录过的每一个访客会话的凭据——而且如果你允许，还能删除全部数据。设计正是由此而来。

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

要警惕任何提供托管端点、让你将请求指向自己实例的 Umami MCP。自行托管的 Umami 没有 API 密钥，因此所谓的“便捷”托管意味着把你的管理员密码寄送到别人的服务器上。

默认最小权限。 服务器以 read 模式启动。扩大权限是一种需要有意为之的行为：

被保留的工具根本不会注册，因此它们永远不会出现在模型的工具列表中。这就是与 READONLY=true 标志不同的地方：一个从未被公开的工具，无法被隐藏在（例如）来源字符串或你自己的分析数据中的页面标题里的提示注入指令调用。没有运行时检查需要忘记或绕过，因为根本没有这个工具。

破坏性操作需要与现实核对过的类型化确认。 umami_delete_website 接受一个 confirmDomain 参数，获取实时记录，并在两者不匹配时拒绝执行。模型如果拿错了网站 UUID，只会得到错误，而不是被清空的数据集。

凭据不进入客户端配置。 服务器不会要求你在 ~/.claude.json 或 mcp.json 中写入密码，而是从你控制的文件 ~/.config/umami-mcp/env 中读取，并在该文件可被其他用户读取时发出警告。参见 凭据。

输出中的机密会被清除。 MCP 输出会流入模型，并且常常进入聊天记录，而聊天记录无法收回。密码、Bearer 令牌和 JWT 会在离开进程之前，从每个错误和响应中被隐去。

拒绝在网络上泄露凭据。 启动时会拒绝向远程主机发送的明文 HTTP；仅允许用于本地开发的 localhost。

安装

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

如果你自行托管并希望在 Claude web 中使用，请在自己的域名后以 UMAMI_MCP_OAUTH=true 运行——这样你的任何数据都不会触及他人的基础设施。

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

在 Claude 中添加一个指向以下地址的自定义连接器：

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

在同意屏幕上，系统会要求你提供自己的 Umami URL 和登录信息。关于凭据的处理方式，请参阅 Claude web、Cowork 和 Claude Code on web。

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 没有 API 密钥，因此这个服务器持有的凭据是一个真实的账户密码。MCP 客户端通常希望将该密码嵌入其配置 JSON——~/.claude.json、mcp.json 等——这些文件可被广泛读取，会被粘贴到 issue 和屏幕共享中，而且某些客户端会在机器之间同步它们。

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

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 web、Cowork 和 Claude Code on web

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

以显而易见的方式托管——内置一组 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_OAUTH 的情况下设置 UMAMI_MCP_TRANSPORT=http，即可在 /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

当服务器绑定到回环地址以外的任何地址时，启动时会发出警告。

工具

时间范围

每个分析工具都接受 period 简写 —— 24h、7d、30d、12m、today、yesterday —— 以替代毫秒级时间戳。模型在"最近 30 天"方面表现可靠，但在时间戳运算方面可靠性欠佳，而错误计算的时间戳会返回错误时间窗口的数据，且不会报错。显式指定毫秒级时间戳的 startAt/endAt 仍可使用，并优先于 period。

配置

有关所有选项，请参阅 .env.example。关键项如下：

推荐部署方式

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

兼容性

已在 Umami 3.3.1（自建、PostgreSQL）上验证。Umami Cloud 可通过 UMAMI_API_KEY 使用。不支持 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 域上创建一个临时网站，然后再将其删除；请将其指向非生产实例。

贡献

欢迎提交 issue 和 pull request。Umami v3 暴露了大约 127 个 API 路由，本服务器覆盖了其中最有用的部分 —— 会话回放、热图、像素追踪、链接跟踪、面板和分群均尚未映射。如果你添加工具，请如实标注权限层级和 destructive 标志，因为整个安全模型都依赖于此。

如果 Umami 团队希望采用、派生或上游集成此服务器，请开启一个 issue —— 这正是构建它的初衷。

许可证

MIT © M Asif Rahman