umami-mcp-server

面向 Umami Analytics 的 MCP 服务器。只读，同时适用于 Umami Cloud 和自托管实例，并使用 last_month 这样的时间范围和 example.com 这样的网站名，而不是 epoch 毫秒和 UUID。

其中包含 25 个工具：网站发现、流量统计、时间序列、排名细分、自定义事件、单个匿名会话、一键式完整报告、网站/用户/团队的完整管理 CRUD、组合式客户开通工具，以及用于 Umami API 中其他任何内容的原始 GET 逃生舱。

管理类工具（创建用户、团队和网站；删除任何内容）需要 自托管的 Umami 实例，并使用管理员登录或管理员 API 密钥。Umami Cloud 不通过 API 暴露用户或团队管理，因此在指向 Cloud 时这些工具会返回明确的错误提示，而不是令人困惑的 404。

安装

npm install
npm run build

Related MCP server: Plausible MCP

配置

复制 .env.example，并选择两种认证方式之一填写。

Umami Cloud

在 Settings > API keys 下创建一个密钥。

自托管

两者通用

接入

Claude Desktop 或 Claude Code

添加到 claude_desktop_config.json，或者运行 claude mcp add：

{
  "mcpServers": {
    "umami": {
      "command": "node",
      "args": ["/absolute/path/to/umami-mcp-server/dist/index.js"],
      "env": {
        "UMAMI_API_KEY": "your-key",
        "UMAMI_TIMEZONE": "America/New_York",
        "UMAMI_DEFAULT_WEBSITE": "example.com"
      }
    }
  }
}

对于自托管实例，请传入 UMAMI_BASE_URL，并使用 API 密钥或用户名密码对。

MCP Inspector

UMAMI_API_KEY=your-key npm run inspect

工具

分析（只读）

管理：网站（自托管、管理员登录或密钥）

管理：用户（自托管、管理员登录或密钥）

管理：团队（自托管或管理员登录或密钥）

开通配置

逃生舱

每个数据工具都支持 response_format：markdown 返回可读摘要，json 返回结构化数据。每个破坏性工具（reset、delete、remove）都必须传入 confirm: true；没有该参数，调用会被拒绝，而且也没有其他确认步骤，因此请把该参数视为不可回头的临界点。

时间范围

range 支持以下任意形式：

• 相对时间：30. 表示、24h、7h、4w、3mo、1y

• 命名时间：today、yesterday、this_week、last_week、this_month、last_month``、this_year、last_year、mtd、ytd、all_time`

或者将 start_date 和 end_date 传为 YYYY-MM-DD 格式、完整的 ISO 8601 时间戳或 epoch 毫秒数。显式日期会覆盖 range。日期边界遵循 UMAMI_TIMEZONE，或通过每次调用传入 timezone 参数指定。

过滤器

大多数工具接受一个 filters 对象来细分查询：

{ "country": "US", "device": "mobile", "path": "/pricing" }

支持的键：path、referrer、title、query、browser、os、device、country、region、city、language、hostname、tag、event、distinctId、utmSource、utmMedium、utmCampaign、utmContent、utmTerm、segment、cohort。

细分维度

适用于 umami_get_metrics 以及 umami_traffic_report 的 breakdowns 参数：path、entry、exit、title、query、referrer、channel、domain、country、region、city、browser、os、device、language、screen、event、hostname、tag、distinctId。

示例

接入后可直接用自然语言提问：

• “网站上月与前一个月的表现相比如何？”→ umami_get_stats，传入 range=last_month

• “给过去 30 天的完整分析报告” → umami_traffic_report

• “哪个落地页的跳出率最高？” → umami_get_metrics，传入 type=entry 和 expanded=true

• “这周的 contact form 提交次数是多少？” → umami_get_events_series，传入 event=contact-form-submit

• “显示佛罗里达州移动端访客访问最多页面” → umami_get_metrics，传入 type=path、filters={ device: "mobile", region: "US-FL" }

• “该会话在网站上实际做了什么？” → 先 umami_list_sessions，再 umami_get_session

• “为新客户开通跟踪、创建其独立团队，并授权给 jordan” → umami_onboard_client，传入 website_name、domain、team_name、grant_user_id

• “上线前清除测试数据” → umami_reset_website，传入 confirm=true

设计说明

• 网站解析。 任何工具的 website 参数都接受一个 UUID、名称或域名。名称和域名会与一份缓存 60 秒的网站列表进行匹配；如果存在歧义，会明确报错，而不是默默地猜错。创建、更新或删除网站都会立即刷新该缓存。

• 完整的回放/热力图配置，而不只是开关。 umami_update_website 会暴露 Umami 的 replayConfig 所接受的全部字段：启用标志、回放和热力图各自独立的采样率、PII 掩码级别、屏蔽选择器，以及最大录制时长。Umami 官方文档对 maxDuration 的单位说明并不一致（一个示例暗示是毫秒，另一个暗示是秒）；与其靠猜，umami_get_recorder_config 会直接读取追踪器（tracker）自身调用的同一个公共端点，因此你可以在保存之后确认实际生效的值，而不是信任任何一个文档示例。

• 派生指标。 Umami 只返回原始的 bounces 和 totaltime 计数；跳出率、每次访问浏览数和平均访问时长都在这里算出，从而让每个响应都直接可读。

• 部分失败。 umami_traffic_report 会并行运行各细分统计，并丢弃当前实例不支持的维度，同时点名哪些维度被跳过，而不是让整个报告失败。这一点很重要，因为不同 Umami 版本对维度的支持情况并不相同。

• 破坏性操作是显式选择，而不需要二次确认。 umami_reset_website、umami_delete_website、umami_delete_user、umami_remove_team_user 和 umami_delete_team 都要求使用字面量 confirm: true 参数，不然就失败。没有独立的“你确定吗”往返过程：工具调用本身就是确认，所以一个 agent（或人）只应该在真正想执行时才传入 confirm: true。

• umami_onboard_client 是尽力而为（best-effort），不是事务性的。 Umami 的 API 不支持多步骤事务。如果团队创建成功、网站步骤却失败，团队仍然保留，错误消息也会明确说明这一点，并指出下一步该检查什么，而不是静默回滚或掩盖这种部分完成状态。

• 逃生出口。 umami_api_get 特意只允许 GET 请求，与支持上面的这些管理工具分开。它不能创建、修改、重置或删除任何内容。

• 响应大小限制。 响应会被限制在 25,000 个字符以内，并提示使用 limit、offset 或更窄的范围。

测试

npm test

test/smoke.mjs 会建起一个假的 Umami API，通过 stdio 连接真实的 MCP 客户端，并完整走一遍数据分析工具及它们的错误路径。test/auth.mjs 覆盖自托管的登录交换，以及缓存的 bearer token 过期时所触发的 token 刷新。test/admin.mjs 覆盖网站/用户/团队 CRUD、团队成员关系、组合 onboarding 工具，并确认任何破坏性工具在没有 confirm=true 时都会拒绝执行。

已验证

依据 Umami v3 API 参考（2026 年 8 月版本）：/websites、/websites/:id、/websites/:id/stats、/pageviews、/metrics、/metrics/expanded、/events/series、/active、/daterange、/sessions、/sessions/:id、/sessions/:id/activity、/websites/:id/reset、/users、/admin/users、/users/:id、/users/:id/websites、/users/:id/teams、/teams、/teams/join、/teams/:id、/teams/:id/users、/teams/:id/users/:userId、/teams/:id/websites。云端请求会发送到 https://api.umami.is/v1 并使用 bearer token；自建（self-hosted）请求会发送到 {base}/api。用户和团队管理端点只存在于自建实例上。

许可证

MIT