1. 项目概述一个为Umami分析平台量身打造的MCP服务器如果你正在使用Umami来追踪你的网站或应用数据并且希望将这些宝贵的数据无缝集成到你的AI工作流中那么Macawls/umami-mcp-server这个项目很可能就是你一直在寻找的那块拼图。简单来说这是一个实现了Model Context ProtocolMCP标准的服务器专门为Umami分析平台提供了一套标准化的工具接口。它的核心价值在于能让你的AI助手比如Claude Desktop、Cursor等支持MCP的客户端直接“读懂”并操作你的Umami数据实现诸如查询实时访问量、获取热门页面、分析用户设备分布等操作而无需你手动登录后台、复制粘贴数据。我最初接触这个项目是因为在尝试用AI辅助进行每周数据复盘时发现过程非常割裂我需要先在Umami后台查看图表然后把关键数字和观察口头描述给AI让它帮我总结。这个过程既低效又容易出错。而这个MCP服务器的出现相当于在AI和你的数据仓库之间架起了一座标准化的桥梁。它不仅仅是一个简单的API包装器更是通过MCP协议将Umami的数据模型和能力转化成了AI能够理解并直接调用的“工具”。对于数据分析师、产品经理、独立开发者或是任何需要频繁与网站数据打交道的角色来说这能极大提升数据查询和洞察生成的效率。2. MCP协议与Umami为何是黄金组合2.1 深入理解Model Context ProtocolMCP要明白这个项目的意义首先得搞清楚MCP是什么。你可以把MCP想象成AI世界里的“USB-C”接口标准。在MCP出现之前每个AI应用客户端想连接不同的数据源或工具服务器可能需要不同的驱动和连接方式非常混乱。MCP由Anthropic提出旨在定义一个统一的协议让任何兼容的AI客户端都能安全、一致地访问任何兼容的数据源和服务。MCP服务器就像本项目的核心工作是两件一是向客户端声明资源二是向客户端提供工具。资源Resources通常是只读的数据比如一份文档、一个数据库表的结构工具Tools则是可执行的操作比如查询、计算、写入等。服务器通过标准化的JSON-RPC over STDIO与客户端通信所有交互都基于清晰的模式定义。这意味着一旦一个工具如“获取网站统计数据”被定义好任何支持MCP的客户端都能以完全相同的方式调用它无需为每个客户端单独开发插件。2.2 Umami轻量、隐私至上的分析平台Umami本身是一个广受欢迎的开源网站分析工具它以其简洁的界面、对用户隐私的尊重GDPR友好无需Cookie提示和出色的性能著称。与Google Analytics等重型方案相比Umami更轻量数据掌握在自己手中部署也相对简单。它提供了清晰的API用于获取网站、页面的各项指标如页面浏览量、独立访客、会话时长、来源渠道等。然而直接使用Umami API仍然需要开发者编写代码、处理认证、解析JSON响应。对于非开发者或希望快速整合到自动化流程中的用户仍有门槛。而Macawls/umami-mcp-server所做的正是将Umami API的复杂性封装起来通过MCP协议暴露出一组语义清晰、开箱即用的工具使得通过自然语言与AI交互来获取数据成为可能。2.3 组合带来的化学反应当MCP的“标准化连接”能力遇上Umami的“纯净数据”时产生的化学反应是显著的。首先它降低了数据访问的技术门槛。你不需要记住复杂的API端点参数只需要告诉AI助手“帮我看看昨天博客的访问来源”AI就能通过调用对应的MCP工具来获取并格式化结果。其次它实现了工作流的无缝集成。你可以在编写产品周报时直接让AI从Umami中提取关键数据并嵌入报告也可以在分析用户行为时通过多轮对话让AI进行交叉查询。最后由于MCP是协议而非特定应用它带来了未来的兼容性和可扩展性。随着更多AI客户端支持MCP你这个Umami服务器的价值会持续放大。3. 项目核心功能与工具拆解Macawls/umami-mcp-server目前实现了一系列针对Umami数据模型的工具。理解这些工具就是理解你能用它来做什么。我们可以将其分为几个核心类别3.1 网站与概览数据查询这是最基础也是最常用的功能集主要围绕“网站”这个核心维度展开。list_websites列出所有网站获取你Umami实例中配置的所有网站列表。通常这是第一个被调用的工具用于确定后续查询的目标网站ID。返回信息包括网站ID、域名、创建时间等。get_website_stats获取网站统计数据针对特定网站查询指定时间范围内的核心聚合指标。这是真正的“主力”工具。你需要提供website_id、start_date和end_date。它会返回该时段内的页面浏览量Pageviews、独立访客Uniques、平均会话时长Avg. Duration和跳出率Bounce Rate等。get_website_metrics获取网站详细指标与get_website_stats类似但可能提供更细粒度或不同聚合方式的数据。具体实现需参考项目文档有时它用于获取时间序列数据。注意Umami的API在时间处理上可能有特定格式要求如ISO 8601。MCP服务器内部会处理这些转换但你通过AI客户端调用时最好使用“YYYY-MM-DD”这样的清晰日期表述避免歧义。3.2 内容与页面分析了解哪些内容最受欢迎是内容运营和SEO优化的关键。get_top_pages获取热门页面查询指定网站在特定时段内按页面浏览量或独立访客排序的页面排名。这对于发现爆款内容、分析用户兴趣点至关重要。返回数据通常包括页面路径、标题如果Umami有记录、访问次数等。get_page_stats获取页面统计数据针对某一个特定的页面URL查询其详细数据。当你需要深入分析某篇特定文章或某个产品页的表现时这个工具就派上用场了。3.3 用户与设备洞察理解你的受众才能更好地服务他们。get_top_referrers获取主要来源分析用户都是从哪些地方跳转过来的。是搜索引擎、社交媒体、还是其他网站的推荐这个工具帮你厘清流量渠道。get_top_browsers/get_top_os/get_top_devices获取主流浏览器/操作系统/设备这一组工具揭示了用户的技术环境。你的用户主要用Chrome还是Safari用手机访问的多还是电脑多这些信息对于前端兼容性测试和响应式设计优化有直接指导意义。get_top_countries/get_top_regions/get_top_cities获取用户地理位置分布了解你的用户来自哪里。这对于本地化服务、内容策略如针对不同地区发布活动或服务器CDN部署都有参考价值。3.4 会话与事件分析进阶一些更深入的行为分析工具可能依赖于Umami的高级功能配置。get_top_sessions获取高互动会话识别出那些停留时间长、浏览页面多的优质会话有助于分析深度用户的行为模式。list_events列出事件如果你在Umami中设置了自定义事件如按钮点击、表单提交、视频播放这个工具可以帮你查询这些事件的触发情况。这是进行转化分析和用户行为漏斗构建的基础。实操心得刚开始使用时不要试图一次性调用所有工具。建议从一个核心需求开始比如“查看我主站上周的整体表现”对应get_website_stats。熟悉了基本的数据结构和交互方式后再逐步尝试更复杂的查询比如“对比一下上周和上上周来自搜索引擎的流量变化”。AI助手客户端能够帮你组合这些工具调用形成复杂的分析链条。4. 从零开始部署与配置指南要让这个MCP服务器跑起来你需要完成服务器端的部署和客户端的配置。下面以最常见的本地开发或自托管场景为例进行详细说明。4.1 环境准备与依赖安装首先确保你的运行环境符合要求。该项目通常基于Node.js环境因此你需要安装Node.js和npm访问Node.js官网下载并安装LTS长期支持版本。安装完成后在终端运行node --version和npm --version确认安装成功。建议Node.js版本在16以上。获取项目代码通过Git克隆仓库是最佳方式便于后续更新。git clone https://github.com/Macawls/umami-mcp-server.git cd umami-mcp-server安装项目依赖进入项目目录后运行npm安装命令。npm install这个过程会下载所有必要的依赖包包括MCP的核心SDK、Umami API客户端、以及各种工具库。4.2 关键配置详解连接你的Umami实例服务器需要知道如何连接到你的Umami实例。配置通常通过环境变量或配置文件完成。核心配置项有以下三个缺一不可UMAmi_BASE_URL你的Umami实例的访问地址。如果你是自己部署的可能是https://analytics.yourdomain.com。如果是使用的官方云服务请对应填写。UMAmi_API_KEY用于认证的API密钥。这是最关键的凭证。如何获取登录你的Umami管理后台通常在“设置”Settings或“API”页面你可以生成一个新的API密钥。请确保该密钥拥有读取数据的必要权限。UMAmi_WEBSITE_ID可选但推荐你默认想要查询的网站ID。虽然每个工具调用时都可以指定website_id但设置一个默认值可以简化大多数查询。你可以在Umami后台的网站列表中找到这个ID。配置方式示例使用.env文件 在项目根目录创建一个名为.env的文件内容如下UMAMI_BASE_URLhttps://your-umami-instance.com UMAMI_API_KEYyour_super_long_api_key_here UMAMI_WEBSITE_IDyour_default_website_uuid然后在启动服务器时这些环境变量会被自动加载。重要安全提示务必妥善保管你的.env文件不要将其提交到公开的Git仓库。在.gitignore文件中加入.env是标准做法。API密钥一旦泄露他人可能读取你的所有分析数据。4.3 启动MCP服务器配置完成后启动服务器就很简单了。根据项目package.json中的定义通常使用以下命令npm start # 或者如果定义了特定脚本 node index.js如果一切正常你会在终端看到服务器已启动的日志它正在标准输入输出stdio上等待MCP客户端的连接。此时服务器本身不会打开一个Web端口供你访问因为它设计为通过stdio与客户端进程间通信。4.4 配置MCP客户端以Claude Desktop为例服务器就绪后需要让你的AI客户端知道它的存在。这里以目前最流行的Claude Desktop为例找到Claude Desktop的配置目录macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json编辑配置文件用文本编辑器打开上述文件。如果文件不存在可以创建它。添加MCP服务器配置在配置文件中你需要添加一个mcpServers对象。关键是指定服务器的启动命令和参数。因为我们的服务器是Node.js脚本需要告诉Claude如何启动它。{ mcpServers: { umami-analytics: { command: node, args: [ /ABSOLUTE/PATH/TO/YOUR/umami-mcp-server/index.js ], env: { UMAMI_BASE_URL: https://your-umami-instance.com, UMAMI_API_KEY: your_super_long_api_key_here, UMAMI_WEBSITE_ID: your_default_website_uuid } } } }command: 这里是node因为我们要用Node.js运行时来执行脚本。args: 数组第一个元素是你的服务器主文件如index.js的绝对路径。请务必替换成你电脑上的实际路径。env: 这里可以直接定义环境变量这样就不需要外部的.env文件了。这样做更便于配置管理。重启Claude Desktop保存配置文件后完全退出并重新启动Claude Desktop应用程序。验证连接重启后当你新建一个对话你应该能在输入框上方或侧边栏看到新添加的工具图标可能是一个图表或Umami的logo。你也可以直接输入“你能用什么工具”或“列出可用的工具”Claude应该会回复它已从umami-analytics服务器加载的工具列表例如get_website_stats、get_top_pages等。踩坑记录我第一次配置时最大的坑在于args里的路径。使用了相对路径./index.js导致Claude启动服务器时找不到文件。必须使用绝对路径。在macOS/Linux上你可以用pwd命令获取当前目录的绝对路径然后拼接上/index.js。在Windows上也需要完整的盘符路径。5. 实战应用场景与对话示例理论说再多不如看实际怎么用。下面我模拟几个真实的工作场景展示如何通过Claude或其他MCP客户端与Umami服务器交互。5.1 场景一快速生成每日/每周数据简报你的需求每天早上你想快速了解核心网站昨天的关键数据形成一个简短的文字简报。你可以对AI说“调用Umami工具帮我查一下默认网站昨天的数据概览然后用简洁的bullet points总结一下。”AI背后的操作与回复AI识别出需要调用get_website_stats工具。它会计算昨天的日期例如今天是2023-10-27则开始和结束日期都是2023-10-26。使用配置中的默认UMAMI_WEBSITE_ID或向你确认网站ID。调用工具收到类似以下的JSON数据{ pageviews: 1245, uniques: 892, bounceRate: 0.42, avgDuration: 186 }AI将数据转化为易读的总结“根据Umami数据昨天2023-10-26你的网站表现如下总页面浏览量1,245次独立访客892人平均会话时长约3分6秒跳出率42%相较于前日页面浏览量增长了约5%独立访客数基本持平平均会话时长有所增加是个积极的信号。”5.2 场景二深度分析内容表现指导内容策略你的需求你写了一篇新的技术文章想看看它发布一周后的表现并与之前同类型的文章进行对比。你可以对AI说“帮我查一下过去7天内路径包含‘/blog/introducing-mcp-server’这个页面的详细数据。另外再列出过去30天最热门的5篇博客文章按页面浏览量我想做个对比。”AI背后的操作与回复AI首先调用get_page_stats工具传入页面路径和时间范围获取该新文章的具体数据浏览量、访客、来源等。接着AI调用get_top_pages工具获取过去30天的热门页面列表并从中筛选出属于博客目录例如路径包含“/blog/”的页面。AI综合两份数据生成分析“关于你的新文章《Introducing MCP Server》过去7天获得了328次浏览来自215个独立访客。主要流量来源是‘Hacker News’占比35%和直接访问占比28%。平均阅读时长达到4分12秒高于网站平均水平说明内容吸引力不错。对比过去30天最热门的5篇博客《如何优化React应用性能》 - 1,842次浏览《深入理解Web3.0》 - 1,550次浏览《我的MCP服务器开发心得》 - 1,200次浏览《2023年前端趋势预测》 - 980次浏览《使用Docker部署Umami》 - 875次浏览你的新文章在一周内达到了328次浏览这个起步速度超过了排名第五的文章同期表现。如果来自Hacker News的流量能持续有望在未来几周冲进月度热门榜。建议可以围绕MCP主题再写1-2篇深度文章形成系列巩固读者群。”5.3 场景三排查异常流量或技术问题你的需求你突然发现服务器负载增高怀疑是否有异常爬虫或某个页面出了问题。你可以对AI说“今天上午10点到现在网站的实时数据有没有异常看看主要来源和使用的浏览器有没有特别的情况。”AI背后的操作与回复AI理解“今天上午10点到现在”是一个自定义时间范围它会计算起止时间。它可能先调用get_website_stats查看整体指标是否有剧烈波动如浏览量激增但会话时长暴跌。然后调用get_top_referrers和get_top_browsers查看短时间内的高频来源和浏览器类型。AI结合结果进行分析“查询了今天10:00至现在的数据总浏览量异常偏高达到平时同时间段的3倍但独立访客数仅增长50%平均会话时长从3分钟降至28秒。流量来源排名第一的是一个陌生的域名aggregator-bot.net贡献了65%的页面浏览。浏览器分布中一个标识为‘Python-urllib/3.10’的客户端占比显著。结论极有可能遭遇了来自aggregator-bot.net的爬虫或扫描器的大量请求疑似使用Python脚本导致数据失真和服务器压力。建议你检查服务器日志确认该IP并考虑在防火墙或Umami设置中屏蔽此类爬虫。”通过这些场景你可以看到将Umami数据以工具的形式赋予AI后数据分析从“手动查询人工分析”变成了“自然语言指令AI自动执行与初步解读”你只需要关注最终的洞察和决策。6. 常见问题、故障排查与进阶技巧在实际使用中你可能会遇到一些问题。这里我总结了一些常见的情况和解决方法。6.1 连接与配置问题问题现象可能原因排查步骤与解决方案Claude Desktop启动后看不到Umami工具1. MCP服务器配置错误。2. Claude Desktop未正确加载配置。3. 服务器启动失败。1.检查配置文件路径和语法确保claude_desktop_config.json格式正确特别是JSON括号和逗号。路径必须是绝对路径。2.彻底重启Claude完全退出包括任务栏/托盘图标再重新打开。3.查看客户端日志Claude Desktop通常有日志输出位置如macOS在~/Library/Logs/Claude查看是否有关于加载MCP服务器的错误信息。4.手动测试服务器在终端中切换到项目目录用配置中的命令和参数手动运行node /path/to/index.js。观察是否有错误输出如API密钥无效、网络错误。调用工具时返回“认证失败”或“无效API密钥”1. API密钥错误或已失效。2. Umami实例地址错误。3. 环境变量未正确传递。1.验证API密钥在Umami后台重新生成一个密钥并更新到配置中。确保密钥有读取权限。2.测试Umami API连通性用curl或Postman直接访问{UMAMI_BASE_URL}/api/websites并带上HeaderAuthorization: Bearer {你的API_KEY}看是否能返回网站列表。3.检查环境变量确保在Claude配置的env字段或服务器的.env文件中变量名拼写完全正确注意大小写。工具调用成功但返回数据为空或只有旧数据1. 查询的时间范围不对。2. 网站ID (website_id) 错误。3. Umami数据有处理延迟。1.确认时间参数Umami通常处理的是UTC时间。确保你传入的日期范围符合预期特别是跨时区时。2.确认网站ID使用list_websites工具核对返回的ID与你配置的是否一致。3.了解数据延迟Umami并非完全实时可能有几分钟到一小时的延迟对于刚发生的访问查询不到是正常的。6.2 性能与使用技巧合理规划查询频率虽然通过AI查询很方便但避免在短时间内发起大量、高频率的查询请求尤其是查询细粒度时间范围如每分钟的数据这可能对Umami数据库造成不必要的压力。对于监控场景合理设置查询间隔。利用好“默认网站ID”如果你90%的查询都针对同一个主站那么在配置中设置好UMAMI_WEBSITE_ID会极大简化你的对话不需要每次都指定网站。组合工具进行复杂分析MCP的强大之处在于AI可以串联多个工具。你可以这样问“对比一下网站A和网站B上周的跳出率并列出它们各自最热门的三个页面。” AI会依次调用get_website_stats分别对A和B和get_top_pages分别对A和B然后整合信息给你一个对比报告。关注项目更新MCP协议和Umami API都可能在发展。关注GitHub仓库的Release和Issue可以及时获取新功能如支持更多Umami API端点或兼容性更新。6.3 安全与隐私考量最小权限原则为MCP服务器使用的API密钥只授予其必要的读取权限。切勿使用拥有管理员权限的API密钥。控制数据访问范围如果你的Umami实例跟踪了多个网站例如公司不同产品线确保通过配置和工具调用AI只能访问它被授权访问的网站数据。可以在对话中明确指定website_id而不是完全依赖默认值。审计日志定期检查Umami后台的API调用日志如果支持了解数据被访问的情况。7. 扩展思考超越查询构建智能数据工作流Macawls/umami-mcp-server项目目前主要聚焦在数据查询这已经解决了“看数据”的核心痛点。但我们可以进一步思考如何利用这个桥梁构建更智能的自动化工作流。想法一异常监控与自动告警。你可以编写一个简单的脚本定期通过cron job调用这个MCP服务器可以将其作为库直接引入或者通过命令行调用获取关键指标如流量暴跌、异常爬虫突增。当检测到异常时自动发送通知到Slack、钉钉或邮件。这样你就有了一个基于自己数据源的、定制化的监控机器人。想法二与内容管理系统CMS联动。假设你在用WordPress或Ghost写博客。当你发布一篇新文章后可以触发一个自动化流程首先通过MCP服务器获取该文章上线初期的数据如首小时阅读量、来源然后结合文章标签和历史数据让AI生成一个初步的传播效果预测或内容优化建议并自动添加到文章的后台备注中。想法三个性化数据报告生成。将MCP服务器与像n8n、Zapier这样的自动化平台连接。每周一早上自动获取上周的数据调用AI可以是同一个Claude也可以是其他大模型API进行分析总结生成一份包含关键指标变化、亮点页面、问题洞察的Markdown报告并自动发布到团队Wiki或发送周报邮件。这个项目的开源性质使得这些扩展成为可能。如果你熟悉Node.js完全可以fork这个项目根据自己Umami的部署情况比如数据库直连或业务需求添加新的工具例如predict_next_week_traffic预测下周流量或find_correlated_pages发现关联页面让AI能做的事情更多。从我个人的使用体验来看Macawls/umami-mcp-server的价值在于它用一种优雅、标准化的方式释放了私有数据的潜力。它不需要你改造现有的Umami部署也不需要对AI客户端有侵入性的修改只是扮演了一个“翻译官”和“接线员”的角色。对于重视数据隐私、又希望享受AI便捷的个人开发者或小团队这是一个非常值得尝试的工具。开始可能会在配置上花点时间但一旦跑通你会发现数据查询和初步分析变得前所未有的流畅自然。