Umami Analytics MCP 服务器

一个模型上下文协议 (MCP) 服务器，通过提供对 Umami 的网站分析数据的访问来增强 Claude 的能力。此服务器允许 Claude 分析用户行为、跟踪网站性能并提供数据驱动的见解。

该代码库已从头到尾使用 Claude Sonnet 3.5 和 Cursor 生成。

功能

此服务器将 Claude 连接到您的 Umami 分析平台，使其能够：

• 分析用户旅程和行为模式
• 跟踪网站性能指标
• 监控实时访客活动
• 捕获和分析网页内容
• 从历史分析数据中生成见解

工作原理

该服务器向 Claude 提供以下工具来分析网站数据：

可用工具

• get_websites: 检索 Umami 帐户中的网站列表及其 ID
• get_website_stats: 获取网站的关键指标，如页面浏览量、访客数、跳出率
• get_website_metrics: 分析特定指标，如 URL、引荐来源、浏览器、国家/地区
• get_pageview_series: 获取具有可自定义间隔的时间序列页面浏览量数据
• get_active_visitors: 监控网站上当前的活跃访客数量
• get_session_ids: 检索特定事件或时间段的会话 ID
• get_tracking_data: 获取特定会话 ID 的详细活动数据
• get_docs: 对许多用户旅程执行语义搜索，返回给定问题的最相关块
• get_screenshot: 捕获网页的可视快照
• get_html: 检索和分析网页 HTML 源代码

每个工具都有一个描述和一个可以传递给它的参数列表。这些用于提供上下文和信息，以便 Claude 能够有效地选择适合工作的工具，并提供正确的参数。

这些工具中的大多数直接从 Umami API 将数据提取到 Claude Desktop 中，但是 get_docs 添加了一个语义搜索步骤，以避免 Claude 的上下文窗口问题，并节省令牌使用量。给定事件的所有用户旅程都使用 Umami API 检索，然后将这些旅程分成更小的部分，并使用来自 hugging face 的开源句子转换器模型进行嵌入。然后，根据问题，检索最相关的块并返回给 Claude，从而可以分析用户在网站上执行的特定操作和行为，这很难用传统的数据可视化工具复制。此嵌入和语义搜索的实现在 src/analytics_service/embeddings.py 文件中。

此外，get_screenshot 和 get_html 工具使用开源 Crawl4AI 网络爬虫来检索给定网站的 HTML 源代码和屏幕截图。必须对屏幕截图进行降采样以减小其大小，以避免 Claude 的上下文窗口问题。这允许您向 Claude 提供有关网站结构和外观的上下文，从而可以更准确和相关地推荐改进网站性能的方法。网络爬虫的实现在 src/analytics_service/crawler.py 文件中。

设置指南

前提条件

• 安装 uv: pip install uv

1. Claude Desktop 配置

   将以下内容添加到您的 Claude Desktop 配置文件中：

   • MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%/Claude/claude_desktop_config.json

   {
     "mcpServers": {
       "analytics_service": {
         "command": "uv",
         "args": [
           "--directory",
           "/path/to/analytics_service",
           "run",
           "analytics-service"
         ],
         "env": {
          "UMAMI_API_URL": "https://example.com",
          "UMAMI_USERNAME": "yourUmamiUsername",
          "UMAMI_PASSWORD": "yourUmamiPassword", 
          "UMAMI_TEAM_ID": "yourUmamiTeamId"
        }
       }
     }
   }
   

   将 /path/to/analytics_service 替换为您的 analytics_service 目录的实际路径。

   对于 UMAMI_API_URL，将 https://example.com 替换为您正在使用的 Umami 版本的 URL（自托管或托管在 Umami Cloud 上）。 对于 UMAMI_USERNAME 和 UMAMI_PASSWORD，将 yourUmamiUsername 和 yourUmamiPassword 替换为您的 Umami 帐户凭据。 对于 UMAMI_TEAM_ID，将 yourUmamiTeamId 替换为您要分析的团队的 ID。

2. 打开 Claude Desktop

当您打开 Claude Desktop 时，它将自动开始连接到 analytics_service MCP 服务器。由于服务器已初始化并且已安装正确的软件包，因此最多需要几分钟。服务器准备就绪后，您将在聊天窗口的右下角看到 10 个可用的 MCP 工具。这用一个小锤子图标和旁边的数字 10 表示。

此外，如果您尚未这样做，强烈建议您在 Claude Desktop 的“功能预览”中启用“分析工具”。这将允许 Claude 为您构建仪表板以及其他数据可视化。为此，在左侧面板中，找到“功能预览”选项卡，然后在其中启用“分析工具”。也可以在同一部分中启用 LaTeX 渲染。

如何使用服务器

入门

最简单的开始方法是使用服务器提供的 创建仪表板提示。通过单击聊天窗口左下角的“从 MCP 附加”附件按钮来选择此选项。然后选择选择实现，然后选择创建仪表板提示。

这将指导您完成为您的网站创建仪表板的过程，要求您提供：

1. 您要分析的网站的名称
2. 分析的开始和结束日期
3. 网站的时区

提供此信息后，服务器将生成一个 txt 文件，指示 Claude 如何构建仪表板。 在聊天窗口中按 Enter 键，Claude 将完成其余操作。然后，您可以要求 Claude 对仪表板进行任何更改或添加任何其他可视化。

自然语言用法

为了获得更可定制的体验，您可以直接与 Claude 交谈并指定您自己的要求，例如您希望在仪表板上看到哪些数据以及您希望使用哪些可视化。此外，您可以分析用户旅程以查明特定的痛点，并添加您网站的屏幕截图，以向 Claude 提供额外的上下文

Claude 将自动使用完成您的请求所需的工具。只需用自然语言提出您的请求，Claude 将决定使用哪些工具。如果您想查看所有可用工具的列表，您可以要求 Claude 为您列出它们，或者单击聊天窗口右下角的锤子图标。

创建您自己的提示

您还可以为您经常使用的工作流程创建自己的提示。为此，您需要：

1. 定义您的提示结构 创建一个提示定义，其中包括：

   • name: 您的提示的唯一标识符
   • description: 对提示作用的清晰解释
   • arguments: 您的提示需要的输入参数列表

   将其添加到 src/analytics_service/server.py 中的 list_prompts() 函数中：

   示例结构：

   @app.list_prompts()
   async def list_prompts():
       return [
           # ... 现有提示 ...
           {
               "name": "您的提示名称",
               "description": "您的提示描述",
               "arguments": [
                   {
                       "name": "参数名称 1",
                       "description": "参数描述",
                       "required": True/False
                   },
                   {
                       "name": "参数名称 2",
                       "description": "参数描述",
                       "required": True/False
                   }
               ]
           }
       ]
   

2. 实现提示 在 src/analytics_service/server.py 中的 get_prompt() 函数中添加您的提示处理逻辑：

   @app.get_prompt()
   async def get_prompt(name: str, arguments: Any):
    # ... 现有提示 ...
       if name == "您的提示名称":
           return {
               "messages": [
                   {
                       "role": "user",
                       "content": {
                           "type": "text",
                           "text": f"您的提示模板，其中包含 {arguments['参数名称']}"
                       }
                   }
               ]
           }
   

   在提示中定义消息时，role 字段对于构建对话至关重要：

   • 对于模拟用户输入或问题的消息，请使用 "role": "user"
   • 对于表示 Claude 的响应或指令的消息，请使用 "role": "assistant"
   • 对于设置上下文或提供高级指令的消息，请使用 "role": "system"

   每个消息中的 content 字段必须指定一个 type。可用类型包括：

   • "type": "text" - 用于纯文本内容
   • "type": "resource" - 用于包含外部资源，如文件、日志或其他数据。必须包含一个 resource 对象，其中包含：
     • uri: 资源标识符
     • text: 实际内容
     • mimeType: 内容的 MIME 类型（例如，“text/plain”、“text/x-python”）

   虽然资源确实在其 text 字段中包含其内容，但使用 resource 类型提供了几个重要的好处：

   1. 内容类型感知: mimeType 字段告诉 Claude 如何解释内容（例如，作为 Python 代码、纯文本或其他格式）
   2. 源跟踪: uri 字段维护对内容来源的引用，这对于以下方面很有用：
      • 跟踪数据的来源
      • 如果源发生更改，则启用更新
      • 提供有关资源位置和用途的上下文
   3. 结构化数据处理: 资源格式允许一致地处理不同类型的内容，同时维护有关每个资源的元数据

   以下示例显示了不同的角色和内容类型：

   "messages": [
       {
           "role": "system",
           "content": {
               "type": "text",
               "text": "分析以下日志文件和代码是否存在潜在问题。"
           }
       },
       {
           "role": "user",
           "content": {
               "type": "resource",
               "resource": {
                   "uri": "logs://recent",
                   "text": "[2024-03-14 15:32:11] ERROR: 连接超时",
                   "mimeType": "text/plain"
               }
           }
       },
       {
           "role": "assistant",
           "content": {
               "type": "text",
               "text": "我注意到连接超时错误。让我检查一下相关的代码。"
           }
       },
       {
           "role": "user",
           "content": {
               "type": "resource",
               "resource": {
                   "uri": "file:///code.py",
                   "text": "def example():\n    pass",
                   "mimeType": "text/x-python"
               }
           }
       }
   ]
   

   对于大多数提示，带有用户角色的文本类型已经足够，并且允许 Claude 在其响应中具有更多的控制权和创造力。但是，对于更复杂的工作流程，具有不同角色和类型的多个消息允许更结构化的对话流程和更多用户对响应的控制。

3. 创建提示的最佳实践

   • 使您的提示集中且具体
   • 包括对参数的明确验证要求
   • 使用描述性名称作为参数
   • 在参数描述中包含示例值
   • 构建提示模板以有效地指导 Claude
   • 考虑错误处理和边缘情况
   • 使用各种输入测试提示