1. 项目概述一个为Umami量身定制的MCP服务器如果你正在使用Umami这个开源的网站分析工具并且希望它能与你日常开发工作流中的其他工具比如代码编辑器、CLI工具、自动化脚本更紧密地结合那么Macawls/umami-mcp-server这个项目很可能就是你一直在寻找的那个“桥梁”。简单来说这是一个实现了模型上下文协议Model Context Protocol MCP的服务器专门用于连接Umami的API让Umami的数据和功能能够以一种标准化的方式被各种支持MCP的客户端例如Claude Desktop、Cursor等AI助手所调用。听起来有点抽象让我打个比方。Umami本身就像一个功能强大的数据仓库你的网站分析数据但它的大门API需要你拿着特定的钥匙编写HTTP请求代码才能打开。而Macawls/umami-mcp-server则是一个智能门卫兼翻译官。它替你保管了钥匙并且当有访客MCP客户端到来时它能理解访客的需求比如“我想看看昨天的页面浏览量”然后帮你从仓库里取出对应的数据并以访客能理解的方式结构化的JSON交给他。这样一来你就不需要每次都亲自去开门、找数据了访客你的AI助手可以自助服务。这个项目的核心价值在于标准化和自动化。它把访问Umami API这个原本需要编写特定代码的操作抽象成了一组标准的“工具Tools”和“资源Resources”。对于开发者或数据分析师而言这意味着你可以在AI助手中直接查询数据无需离开代码编辑器或聊天界面就能问“我网站上访问量最高的五个页面是哪些”并立刻得到答案。构建自动化工作流将Umami的数据作为其他自动化流程的输入比如当某个关键页面的跳出率异常升高时自动发送通知。降低集成成本任何支持MCP的客户端都能以相同的方式接入无需为每个工具单独编写Umami的集成代码。接下来我将为你深入拆解这个项目的设计思路、核心实现、以及如何将它应用到你的实际工作中。1.1 为什么需要为Umami构建MCP服务器要理解这个项目的必要性我们得先看看没有它的时候我们是怎么和Umami交互的。通常获取Umami数据的方式有两种登录Web管理后台查看仪表盘或者通过其RESTful API编程获取。前者适合人工浏览后者适合系统集成。但在AI原生的工作流中这两种方式都存在断层。当你正在使用Claude或Cursor编写代码、撰写文档时突然想确认一下刚刚部署的新功能对网站流量的影响你就不得不1打开浏览器2登录Umami控制台3筛选时间范围和指标。这个过程打断了你当前的工作上下文。而使用API虽然可以编程获取但你需要在另一个终端或脚本里运行代码数据也无法直接与你当前的对话或编辑上下文关联。MCP协议正是为了解决这种“上下文割裂”问题而诞生的。它允许外部服务器如umami-mcp-server向客户端如AI助手声明“我这里有这些工具查询页面浏览量、获取实时用户数和资源网站列表、指标定义你可以随时调用。” 这样AI助手就能在对话中无缝地使用这些能力仿佛它是内置功能一样。因此为Umami构建MCP服务器本质上是为了将Umami的数据能力注入到AI助手的上下文中创造一种“对话即查询”的体验。这不仅仅是方便更是一种工作范式的转变让数据获取变得像提问一样自然。1.2 核心组件与架构解析Macawls/umami-mcp-server的实现基于Node.js这是一个非常自然的选择因为Umami本身也是Node.js应用且JavaScript生态对构建HTTP服务器和API客户端有丰富的支持。项目的架构清晰体现了MCP服务器的核心职责。1. MCP服务器骨架Server Core项目核心是建立了一个符合MCP规范的HTTP/SSEServer-Sent Events服务器。它使用modelcontextprotocol/sdk这个官方SDK来简化开发。这个SDK处理了与MCP客户端之间复杂的握手、协议版本协商、工具列表同步等底层通信细节。开发者的主要工作就是聚焦在定义“我有什么工具”和“我有什么资源”。2. 工具Tools定义与实现这是项目的业务逻辑核心。每一个工具对应一个Umami API的能力。例如get_website_stats工具可能封装了Umami的/websites/[id]/stats端点用于获取某个网站在特定时间段内的核心指标页面浏览量、独立访客等。get_realtime_activity工具封装/websites/[id]/active端点获取当前实时在线用户信息。list_websites工具封装/websites端点获取用户有权限访问的所有网站列表。每个工具的实现都遵循相似的模式接收来自客户端的参数如websiteId、startDate、endDate将其转换为对Umami API的HTTP请求处理响应包括错误处理最后将数据格式化为MCP协议要求的格式返回给客户端。3. 资源Resources声明除了主动调用的工具MCP还支持“资源”。资源可以理解为一些只读的、URI可寻址的数据块。在这个项目中可能会将“网站列表”或“指标说明文档”声明为资源。客户端可以像读取文件一样读取这些资源的内容从而获得静态或半静态的上下文信息。例如AI助手在提供帮助前可以先读取umami://websites/list这个资源了解用户有哪些可分析的网站从而提供更精准的建议。4. 配置与认证管理安全地访问Umami API是关键。项目需要处理如何让用户配置其Umami实例的地址URL和API密钥。通常这会通过环境变量或配置文件来实现。服务器启动时会读取这些配置并在后续所有向Umami发起的请求中在HTTP头部携带正确的Authorization: Bearer API_KEY信息。整个数据流可以概括为MCP客户端发起工具调用请求 - umami-mcp-server接收并解析请求 - 使用存储的配置向Umami API发起请求 - 接收Umami API的JSON响应 - 将响应加工后返回给MCP客户端。2. 从零开始部署与配置指南理解了项目是什么以及为什么之后我们来看看如何让它跑起来。以下步骤假设你已经在本地或服务器上运行了一个Umami实例并且拥有一个有效的API密钥。2.1 环境准备与依赖安装首先你需要一个Node.js运行环境。建议使用LTS版本如Node.js 18。你可以通过node -v和npm -v来检查是否已安装。接下来获取项目代码。由于这是一个开源项目你可以直接从GitHub仓库克隆git clone https://github.com/Macawls/umami-mcp-server.git cd umami-mcp-server进入项目目录后安装所有必要的依赖包。项目根目录下的package.json文件定义了所有依赖。npm install注意如果遇到网络问题导致npm install缓慢或失败可以考虑配置npm镜像源。但请务必通过官方或可信渠道获取镜像地址并仅用于加速公共、合法的开源包下载。安装依赖是标准开发流程无需也不应涉及任何非法的网络访问手段。安装过程完成后你会看到node_modules文件夹被创建所有依赖包括MCP SDK、HTTP客户端库等都已就位。2.2 关键配置项详解项目运行需要知道你的Umami在哪里以及如何认证。配置通常通过环境变量来设置这是12-Factor应用的标准实践也便于在不同环境开发、生产间切换。你需要准备以下两个核心配置UMAMI_API_URL你的Umami实例的API基础地址。如果你的Umami部署在https://analytics.yourdomain.com那么API地址通常是https://analytics.yourdomain.com/api。务必确保地址正确且末尾的/api路径无误。UMAMI_API_KEY你的Umami API密钥。你可以在Umami的Web管理界面中生成它。通常路径是登录Umami - 设置Settings - API密钥API Keys - 生成新密钥Generate new key。请妥善保管此密钥它拥有访问你数据的权限。设置环境变量有多种方式。在Linux/macOS的终端中你可以直接导出export UMAMI_API_URLhttps://analytics.yourdomain.com/api export UMAMI_API_KEYyour_umami_api_key_here在Windows的PowerShell中使用$env:UMAMI_API_URLhttps://analytics.yourdomain.com/api $env:UMAMI_API_KEYyour_umami_api_key_here为了持久化和方便管理更常见的做法是创建一个.env文件在项目根目录。项目通常会使用dotenv这样的库来读取它。# 在项目根目录创建 .env 文件 echo UMAMI_API_URLhttps://analytics.yourdomain.com/api .env echo UMAMI_API_KEYyour_umami_api_key_here .env重要安全提示.env文件包含了敏感信息绝对不要将其提交到Git等版本控制系统。确保它在.gitignore文件中。在Docker或CI/CD环境中应使用相应的秘密管理服务来注入这些变量。2.3 启动服务器与验证配置完成后启动服务器就非常简单了。查看package.json中的scripts部分通常会有启动命令。npm start # 或者如果定义了开发脚本 npm run dev如果一切正常终端会输出服务器启动的日志表明它正在某个端口比如3000监听来自MCP客户端的连接。日志可能会显示类似Umami MCP server started on port 3000或Server listening on http://localhost:3000的信息。为了验证服务器是否正常工作并且能正确连接到你的Umami实例你可以进行一个简单的健康检查。通常MCP服务器会暴露一个简单的HTTP端点用于检查。你可以用curl命令测试curl http://localhost:3000/health如果返回OK或类似的成功信息说明服务器进程本身是健康的。更进一步的验证需要连接MCP客户端来进行我们将在下一部分详细展开。3. 与MCP客户端集成实战服务器跑起来只是第一步让它发挥作用的关键是与MCP客户端连接。这里我以目前最流行的两个客户端——Claude Desktop和Cursor为例详细讲解集成步骤。3.1 配置Claude Desktop连接Claude Desktop是Anthropic官方推出的客户端内置了对MCP的支持。配置过程主要是编辑一个配置文件。定位配置文件macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json编辑配置文件如果文件不存在就创建它。你需要添加一个mcpServers配置项。关键是指定服务器的启动命令和运行时环境。{ mcpServers: { umami: { command: node, args: [ /ABSOLUTE/PATH/TO/umami-mcp-server/build/index.js // 替换为你的绝对路径 ], env: { UMAMI_API_URL: https://analytics.yourdomain.com/api, UMAMI_API_KEY: your_umami_api_key_here } } } }参数详解command: 运行服务器的命令这里是node。args: 传递给命令的参数即你的服务器入口文件编译后的JS文件的绝对路径。如果你直接运行源码路径可能是index.js。env: 在这里直接定义环境变量这是最直接的方式避免了在系统层面设置。注意将your_umami_api_key_here替换为你的真实密钥。实操心得使用绝对路径是最可靠的方式。相对路径可能会因为Claude Desktop的工作目录不同而导致找不到文件。你可以通过在终端中进入项目目录并执行pwdLinux/macOS或cdWindows来获取当前绝对路径然后拼接上/build/index.js。重启与验证保存配置文件后完全退出并重启Claude Desktop。重启后当你新建一个对话时Claude应该会加载MCP服务器。你可以尝试问它“你能用Umami帮我做什么” 或者直接发出指令“查询一下我主站昨天的总页面浏览量。” 如果配置成功Claude会识别到可用的工具并调用它们。3.2 配置Cursor编辑器连接Cursor是另一款深度集成AI的代码编辑器它也支持MCP。配置方式与Claude Desktop类似但配置文件的位置和格式略有不同。定位配置文件Cursor的配置通常在其设置Settings中或者通过一个全局配置文件。更常见的方式是在你的项目根目录下创建一个.cursor/mcp.json文件。这样配置可以做到项目级别隔离。编辑配置文件在项目根目录创建.cursor文件夹并在其中创建mcp.json文件。{ mcpServers: { umami: { command: node, args: [ ./build/index.js // 相对于项目根目录的路径 ], env: { UMAMI_API_URL: ${config:UMAMI_API_URL}, UMAMI_API_KEY: ${config:UMAMI_API_KEY} } } } }参数详解args: 这里使用了相对路径./build/index.js因为Cursor会以包含.cursor文件夹的目录即项目根目录作为当前工作目录来启动服务器。这比绝对路径更灵活。env: 这里使用了变量引用${config:...}。这意味着你需要先在Cursor的全局或项目设置中定义这些配置变量。你可以在Cursor的设置界面搜索“MCP”或“环境变量”进行设置。这样做的好处是密钥不直接暴露在配置文件中。替代方案使用全局配置你也可以在Cursor的全局配置中设置MCP服务器这样对所有项目生效。具体位置可能在~/.cursor/mcp.json类Unix系统或%APPDATA%\Cursor\mcp.jsonWindows。格式与上述相同。验证配置完成后在Cursor中打开一个文件然后唤出AI聊天面板通常是Cmd/Ctrl K。你可以询问AI“列出我的Umami网站。” 如果配置正确Cursor AI会调用list_websites工具并返回结果。3.3 常用工具调用示例与技巧成功连接后你就可以在对话中自然地使用Umami的能力了。以下是一些典型的使用场景和提问技巧基础数据查询“帮我看看网站ID为[your-website-id]在过去7天的页面浏览量和独立访客数。”“我的网站在今天有多少实时在线用户”“对比一下上周和这周的跳出率。”获取资源列表“我有哪些可以查看的网站”触发list_websites工具或读取网站列表资源“告诉我get_website_stats这个工具需要哪些参数”AI可以读取工具的模式定义来回答进阶分析与组合提问“找出昨天访问量最高的三个页面并告诉我它们的平均停留时间。”“最近一周来自Chrome浏览器的流量占比是多少”“创建一个摘要总结我的主站在本月的主要流量指标并与上月对比。”注意事项AI助手的能力取决于MCP服务器暴露的工具粒度。如果umami-mcp-server只提供了基础的聚合数据工具那么像“找出跳出率最高的页面”这样的复杂查询可能无法直接完成。这需要服务器端实现更复杂的、组合了多个Umami API调用的工具。因此在实际使用前最好先了解该服务器具体实现了哪些工具通常会在项目README中列出。4. 核心功能实现深度解析了解了如何使用我们再来深入看看umami-mcp-server内部是如何运作的。这对于你想自定义功能、排查问题或者学习MCP开发都大有裨益。4.1 Umami API客户端封装服务器与Umami的交互是通过一个封装好的API客户端完成的。这个客户端负责处理所有HTTP通信的细节是项目稳健性的基石。1. 基础请求构造 客户端首先会基于配置的UMAMI_API_URL构建基础URL。所有请求都会使用Fetch API或axios这样的HTTP库发起。关键在于每个请求都必须在头部附加认证信息const headers { Authorization: Bearer ${apiKey}, Content-Type: application/json };2. 参数处理与序列化 Umami API的许多端点需要查询参数如startAt,endAt,unit等。客户端需要将JavaScript对象转换成URL查询字符串。例如{startAt: ‘2024-01-01’, endAt: ‘2024-01-07’}需要转换成?startAt2024-01-01endAt2024-01-07。同时对于POST请求需要将body对象序列化成JSON字符串。3. 错误处理与重试 网络请求可能失败。一个健壮的客户端必须包含错误处理逻辑。这包括检查HTTP状态码非2xx状态码如401未授权、404未找到、500服务器错误需要被捕获并转换成对用户或MCP客户端友好的错误信息。网络异常处理处理fetch或axios抛出的网络错误、超时等。可选的指数退避重试对于偶发的网络错误或5xx服务器错误可以实现简单的重试机制增加系统的鲁棒性。4. 响应数据转换 Umami API返回的数据格式是固定的。MCP客户端期望的工具调用结果也有其格式。API客户端的最后一个职责就是将Umami的原始响应转换成MCP工具结果所需的格式。通常这包括提取核心的data字段并可能进行一些简单的重组或重命名以使得返回的数据结构更清晰、更自描述。4.2 MCP工具Tools的具体实现这是业务逻辑的核心。我们以get_website_stats工具为例拆解其实现步骤。1. 工具定义Declaration 首先需要使用MCP SDK创建一个工具定义对象。这个对象告诉MCP客户端“这个工具叫什么、需要什么参数、返回什么、以及一段描述”。const getWebsiteStatsTool { name: “get_website_stats”, description: “获取指定网站在特定时间段内的统计指标如页面浏览量、访客数等。”, inputSchema: { type: “object”, properties: { websiteId: { type: “string”, description: “Umami中的网站唯一标识符” }, startAt: { type: “string”, description: “开始时间ISO 8601格式例如 2024-01-01T00:00:00.000Z” }, endAt: { type: “string”, description: “结束时间ISO 8601格式” }, // 可能还有其他Umami支持的参数如 unit时间粒度 }, required: [“websiteId”] // websiteId是必填项 } };2. 工具处理函数Handler 当MCP客户端调用这个工具时对应的处理函数会被执行。这个函数接收一个包含参数的context对象。async function handleGetWebsiteStats({ websiteId, startAt, endAt /*, otherParams */ }) { // 1. 参数验证与默认值填充 if (!websiteId) { throw new Error(“websiteId is required”); } const now new Date(); const defaultStart new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000); // 默认过去7天 const queryStart startAt || defaultStart.toISOString().split(‘T’)[0]; // 取日期部分 const queryEnd endAt || now.toISOString().split(‘T’)[0]; // 2. 调用封装好的Umami API客户端 const stats await umamiApiClient.getWebsiteStats(websiteId, { startAt: queryStart, endAt: queryEnd, // unit: ‘day’ // 可以按需添加 }); // 3. 格式化返回结果符合MCP协议要求 return { content: [ { type: “text”, text: 网站 ${websiteId} 在 ${queryStart} 至 ${queryEnd} 期间的统计数据\n 总页面浏览量: ${stats.pageviews}\n 总独立访客: ${stats.visitors}\n 平均停留时长: ${stats.avgDuration} 秒 // 也可以返回更结构化的数据便于AI进一步处理 // type: “object”, // object: stats } ] }; }3. 工具注册 最后在服务器初始化时需要将这个工具定义和处理函数注册到MCP服务器实例中。server.setRequestHandlerMcpServer.tools.list, async { tools: [getWebsiteStatsTool] // 注册工具定义 }); server.setRequestHandlerMcpServer.tools.call, async request { if request.params.name “get_website_stats” { return await handleGetWebsiteStatsrequest.params.arguments; } // ... 处理其他工具 };通过这样的模式每一个Umami API的能力都被包装成了一个独立的、自描述的MCP工具。4.3 错误处理与日志记录策略在生产环境中健壮的错误处理和清晰的日志至关重要。错误处理层级工具参数验证错误在工具处理函数入口处检查必填参数、参数格式如日期格式。这类错误应直接返回清晰的错误信息给用户。Umami API调用错误在API客户端层捕获HTTP错误和网络错误。将Umami返回的API错误信息如果有向上传递并补充上下文如请求的URL、参数。最终返回给客户端的错误信息应友好且可操作例如“无法连接到Umami服务器请检查网络和配置”或“API密钥无效访问被拒绝401”。MCP协议层错误MCP SDK本身可能会抛出错误例如消息格式错误。这些通常由SDK内部处理但服务器应确保进程不会因此崩溃。日志记录 建议使用结构化的日志库如winston或pino。记录以下关键信息信息级Info服务器启动、工具被调用记录工具名和关键参数注意过滤掉敏感参数如API密钥。警告级Warn参数缺失使用了默认值、API返回了非关键性警告。错误级Error所有捕获到的异常包括完整的错误堆栈、相关请求ID如果有、触发的工具名。这对于事后排查问题至关重要。日志应同时输出到控制台便于开发调试和文件便于生产环境追溯。对于文件日志要实施日志轮转策略避免单个文件过大。5. 高级应用、问题排查与扩展方向当你熟练使用基础功能后可能会想探索更高级的用法或者遇到一些问题。这一部分将分享一些进阶思路和实战中可能遇到的坑。5.1 构建自动化数据分析工作流MCP服务器的价值不仅在于交互式查询更在于它能成为自动化流程中的一个可靠组件。结合脚本或其他自动化工具你可以实现每日/每周报告自动生成编写一个简单的Node.js脚本或使用Python的requests库作为MCP客户端调用umami-mcp-server的工具获取关键指标然后通过模板生成HTML或Markdown报告最后通过邮件或Slack发送。异常监控与告警定时调用get_website_stats工具获取当前小时或当天的关键指标如流量暴跌、错误率飙升并与阈值比较。如果超过阈值则触发告警如调用飞书、钉钉或PagerDuty的Webhook。与BI工具联动虽然Umami有自己的看板但你可能需要将数据接入更强大的BI工具如Metabase、Tableau。你可以定期通过MCP服务器提取原始数据存入数据库如PostgreSQL供BI工具直接查询。实现这些的关键是你需要另一个程序作为MCP客户端。你可以使用官方的modelcontextprotocol/sdk来编写一个轻量级客户端或者寻找社区已有的通用MCP客户端库。5.2 常见问题与故障排除在部署和使用过程中你可能会遇到以下问题1. 连接失败MCP客户端无法连接到服务器症状Claude Desktop或Cursor提示无法加载MCP服务器或连接超时。排查步骤检查服务器进程首先确认umami-mcp-server是否正在运行。使用ps aux | grep node或查看终端输出。检查端口占用确认服务器监听的端口如3000没有被其他程序占用。检查客户端配置仔细核对配置文件中的command和args路径。绝对路径是最可靠的。确保Node.js在系统PATH中。检查防火墙如果服务器运行在远程机器确保客户端能访问该机器的对应端口。2. 认证错误服务器无法访问Umami API症状工具调用后返回“认证失败”、“401 Unauthorized”或类似的错误。排查步骤验证环境变量在服务器运行的环境下执行echo $UMAMI_API_KEYLinux/macOS或echo %UMAMI_API_KEY%Windows确认密钥已正确设置且未被截断。手动测试API使用curl命令直接测试Umami API这是最直接的验证方式curl -H “Authorization: Bearer YOUR_API_KEY” “https://analytics.yourdomain.com/api/websites”如果这个命令也失败说明问题出在API密钥或Umami服务本身而非MCP服务器。检查密钥权限确认你的API密钥拥有访问目标网站数据的权限。3. 工具调用无结果或数据不符症状工具调用成功但返回空数组、0值或数据与Web控制台显示的不一致。排查步骤核对网站ID确保传递给工具的websiteId参数完全正确。它应该是一个UUID字符串可以在Umami控制台的网站设置里找到。核对时间参数检查startAt和endAt参数的格式和时区。Umami API通常期望UTC时间或特定格式的日期字符串。确保你传递的时间范围覆盖了预期有数据的时间段。时间粒度问题某些聚合数据可能依赖于查询的unit如hour,day,month。如果使用默认值或错误粒度可能导致数据聚合方式不符合预期。4. 性能问题查询响应缓慢症状AI助手调用工具后需要等待很长时间才有响应。可能原因与优化Umami API本身慢如果查询的时间范围很大如一年Umami数据库可能需要较长时间聚合。尝试缩小查询范围或确认Umami数据库是否有性能瓶颈。网络延迟MCP服务器和Umami实例之间的网络延迟。确保它们部署在相近的网络环境或同一内网。服务器资源不足运行MCP服务器的机器CPU或内存不足。监控服务器资源使用情况。5.3 项目扩展与二次开发建议开源项目的魅力在于可以按需定制。如果你觉得现有的工具不够用可以考虑以下扩展方向1. 添加新的工具 研究Umami的官方API文档找到你需要的端点。然后仿照get_website_stats的模式在项目中添加新的工具定义和处理函数。例如get_page_stats: 获取特定页面的详细数据。get_event_data: 查询自定义事件。create_website: 通过API创建新的网站需要POST请求。2. 实现更复杂的聚合工具 现有的工具可能只是简单封装单个API。你可以实现更“智能”的工具例如compare_periods: 接收两个时间范围自动调用两次API并计算关键指标的增长率。top_pages: 获取访问量最高的N个页面并附带其平均停留时间和跳出率。3. 改进资源Resources 除了工具可以声明更多有用的资源例如umami://docs/metrics: 一个包含所有Umami指标定义和计算方法的文档资源帮助AI助手更好地理解数据。umami://websites/{id}/info: 动态资源根据URI中的网站ID返回该网站的配置信息。4. 增强配置管理支持从YAML或JSON配置文件读取多个Umami实例配置。实现配置的热重载无需重启服务器即可更新API密钥。进行二次开发时请务必先仔细阅读项目的源代码结构理解其模块划分。通常工具定义会放在src/tools/目录API客户端在src/api/主服务器逻辑在src/server.js或index.js。修改后记得更新README.md文档说明新增的功能。这个项目为Umami的数据能力打开了一扇新的大门让它从孤立的数据看板变成了可编程、可对话、可集成的智能数据源。无论你是想提升个人工作效率还是为团队构建更智能的数据洞察流程它都提供了一个坚实且富有潜力的起点。