Umami MCP 服务器

用于 Umami 分析的只读 MCP 服务器。它通过 HTTP 直接与 Umami REST API 通信，优先支持自托管 Umami，同时也适用于 Umami Cloud API 密钥。

构建此仓库的目的是让上层代理能够获取分析数据，而无需每次都重新阅读 Umami 文档。不涉及浏览器自动化、DOM 抓取或写入操作。

功能特性

针对最常见 Umami 分析查询的只读 MCP 工具
两种认证模式：
- UMAMI_API_KEY
- UMAMI_USERNAME + UMAMI_PASSWORD
内存中自托管 Bearer 令牌缓存
用户名/密码模式下自动重新登录并在 401 错误时重试一次
同时支持 ISO 时间字符串和毫秒级时间戳
跨统计、页面浏览量、细分数据和事件序列的共享过滤器处理
严格的 TypeScript，模块小巧且易于维护
清晰的结构化工具输出和明确的错误分类

要求

Node.js >= 20
pnpm >= 10

安装

从 npm 安装：

npm install -g umami-analytics-mcp

或者直接运行，无需安装：

npx -y umami-analytics-mcp

在本仓库进行本地开发：

pnpm install

配置

从 .env.example 创建一个 .env 文件。

cp .env.example .env

填写以下任一认证选项：

API 密钥模式

UMAMI_API_URL=https://api.umami.is/v1
UMAMI_API_KEY=your-api-key
UMAMI_DEFAULT_TIMEZONE=Asia/Shanghai

自托管用户名/密码模式

UMAMI_API_URL=https://umami.example.com/api
UMAMI_USERNAME=admin
UMAMI_PASSWORD=secret
UMAMI_DEFAULT_TIMEZONE=Asia/Shanghai

注意：

UMAMI_API_URL 应指向 API 根路径，而不仅仅是站点源地址。
如果同时设置了 UMAMI_API_KEY 和用户名/密码，则 UMAMI_API_KEY 优先。
当工具支持时区且你未指定时，将使用 UMAMI_DEFAULT_TIMEZONE。

本地运行

开发模式：

pnpm dev

构建并运行：

pnpm build
pnpm start

该服务器使用 MCP stdio 传输，因此它会保持连接到 stdin/stdout，直到客户端断开连接。

如果通过 npm 安装，等效命令为：

umami-analytics-mcp

测试

pnpm test
pnpm build

还有一个默认跳过的真实 API 集成测试模板：

UMAMI_INTEGRATION_TEST=1 pnpm test:integration

MCP Inspector

先构建：

pnpm build

然后针对构建好的服务器启动官方 MCP Inspector：

npx @modelcontextprotocol/inspector node dist/cli.js

开发期间的热重载也适用：

npx @modelcontextprotocol/inspector pnpm dev

如果你想测试已发布的包路径，请使用：

npx @modelcontextprotocol/inspector npx -y umami-analytics-mcp

确保 Inspector 进程可以使用相同的 Umami 环境变量。

推荐在 Inspector 中进行的冒烟测试调用：

umami_ping
umami_list_websites
umami_get_stats
umami_get_breakdown

工具

`umami_ping`

验证配置和认证。

示例：

{}

`umami_list_websites`

列出可访问的网站。

示例：

{}

`umami_find_website`

按网站名称或域名进行模糊搜索。

示例：

{
  "query": "example.com"
}

`umami_get_stats`

网站和时间范围的汇总统计数据。

示例：

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-23T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "filters": {
    "path": "/pricing"
  }
}

`umami_get_pageviews`

时间序列的页面浏览量和会话数。

示例：

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-17T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "unit": "day",
  "compare": "prev",
  "filters": {
    "path": "/blog"
  }
}

`umami_get_breakdown`

细分行数据，如热门页面、引荐来源、国家/地区、浏览器、设备等。

示例：

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-17T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "type": "path",
  "limit": 10,
  "expanded": false
}

`umami_get_active`

返回当前活跃访客数。

示例：

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab"
}

`umami_get_events_series`

返回随时间变化的自定义事件计数。

示例：

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-17T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "unit": "day"
}

共享过滤器

这些工具支持相同的 filters 对象：

path
referrer
title
query
browser
os
device
country
region
city
hostname

错误处理

工具错误以结构化的 MCP 工具结果返回，包含以下类别：

config_missing
auth_failed
website_not_found
umami_http_error
network_timeout
network_error
invalid_input

在任何 Stdio MCP 客户端中挂载

任何基于 stdio 的 MCP 客户端都可以通过以下方式运行此服务器：

command: npx
args: ["-y", "umami-analytics-mcp"]
env: 你的 Umami 变量

对于使用 mcpServers 对象的客户端，JSON 代码片段示例：

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "umami-analytics-mcp"],
      "env": {
        "UMAMI_API_URL": "https://umami.example.com/api",
        "UMAMI_USERNAME": "admin",
        "UMAMI_PASSWORD": "secret",
        "UMAMI_DEFAULT_TIMEZONE": "Asia/Shanghai"
      }
    }
  }
}

对于本地未发布的检出版本，你仍然可以直接指向构建后的文件：

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

发布到 npm

此仓库现已结构化为 npm CLI 包。

推荐的发布流程：

pnpm test
pnpm build
pnpm pack --dry-run
npm login
pnpm publish

注意：

包名称设置为 umami-analytics-mcp，因为 umami-mcp 在 npm 上已被占用。
当前 license 为 UNLICENSED，作为安全的占位符。如果你想要一个宽松的许可证，请在正式公开开源发布之前替换它。
如果你以后在自己的 npm 作用域下发布，只需更改 package.json 中的 name 字段。

内部文档

本仓库使用的 API 摘要：docs/umami-api.md

Umami MCP Server