Umami Analytics MCP Server

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 的上下文窗口问题并节省 token 用量。系统会使用 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 的 Feature Preview 中启用“Analysis tool”。这样 Claude 就能为你构建仪表板以及其他数据可视化内容。要启用此功能，请在左侧面板中找到“Feature Preview”标签页，并启用其中的“Analysis tool”。你也可以在同一位置启用 LaTeX Rendering。

如何使用服务

入门

最简单的入门方式是使用服务提供的 Create Dashboard Prompt。点击聊天窗口左下角的“Attach from MCP”附件按钮，然后选择“choose implementation”，再选择“Create Dashboard Prompt”。

该提示词会引导你为网站创建仪表板，并询问：

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 [
           # ... existing prompts ...
           {
               "name": "Your Prompt Name",
               "description": "Your prompt description",
               "arguments": [
                   {
                       "name": "Parameter Name 1",
                       "description": "Parameter description",
                       "required": True/False
                   },
                   {
                       "name": "Parameter Name 2",
                       "description": "Parameter description",
                       "required": True/False
                   }
               ]
           }
       ]
   

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

   @app.get_prompt()
   async def get_prompt(name: str, arguments: Any):
    # ... existing prompts ...
       if name == "Your Prompt Name":
           return {
               "messages": [
                   {
                       "role": "user",
                       "content": {
                           "type": "text",
                           "text": f"Your prompt template with {arguments['Parameter Name']}"
                       }
                   }
               ]
           }
   

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

   • 使用 "role": "user" 表示模拟用户输入或提问的消息
   • 使用 "role": "assistant" 表示 Claude 的回复或指令
   • 使用 "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": "Analyze the following log file and code for potential issues."
           }
       },
       {
           "role": "user",
           "content": {
               "type": "resource",
               "resource": {
                   "uri": "logs://recent",
                   "text": "[2024-03-14 15:32:11] ERROR: Connection timeout",
                   "mimeType": "text/plain"
               }
           }
       },
       {
           "role": "assistant",
           "content": {
               "type": "text",
               "text": "I notice a connection timeout error. Let me examine the related code."
           }
       },
       {
           "role": "user",
           "content": {
               "type": "resource",
               "resource": {
                   "uri": "file:///code.py",
                   "text": "def example():\n    pass",
                   "mimeType": "text/x-python"
               }
           }
       }
   ]
   

   对于大多数提示词，使用 user 角色的文本类型就足够了，而且能让 Claude 在回复中拥有更多控制权和创造性。不过，对于更复杂的工作流，使用不同角色和类型的多条消息可以让对话流程更有条理，并让用户更好地控制回复。

3. 创建提示词的最佳实践

   • 让提示词聚焦且具体
   • 明确说明参数的验证要求
   • 为参数使用描述性名称
   • 在参数说明中加入示例值
   • 设计提示词模板，有效引导 Claude
   • 考虑错误处理和边缘情况
   • 使用各种输入测试提示词