Umami Analytics MCP Server

Umami分析MCP服务器

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

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

alt text

它做什么

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

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

运作原理

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

可用工具

• get_网站：检索您的Umami帐户中的网站及其ID列表
• get_website_stats：获取网站的页面浏览量、访问者、跳出率等关键指标
• get_website_metrics：分析特定指标，如网址、推荐人、浏览器、国家
• get_pageview_series：获取具有可自定义间隔的时间序列页面浏览量数据
• get_active_visiors：监控网站上当前活跃访问者的数量
• get_session_ids：检索特定事件或时间段的会话ID
• 获取跟踪数据：获取特定会话ID的详细活动数据
• get_docs：在许多用户旅程中执行语义搜索，返回给定问题的最相关块
• get_creenshot：捕获网页的视觉快照
• get_html：检索和分析网页HTML源代码

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

这些工具大多直接从Umami API将数据拉入Claude Desktop，但get_docs添加了语义搜索步骤，以避免Claude出现上下文窗口问题，并节省令牌使用。使用Umami API检索给定事件的所有用户旅程，然后将这些旅程分为较小的部分，并使用拥抱面部的开放式soruce句子转换模型嵌入。然后，根据问题，检索最相关的块并将其返回给Claude，从而可以分析用户在网站上执行的具体操作和行为，这是传统数据可视化工具难以复制的。这种嵌入和语义搜索的实现在 src/analytics_service/embeddings.py 文件。

此外，get_creenshot和get_html工具使用开源 Crawl4AI 网络爬虫，用于检索给定网站的HTML源代码和屏幕截图。必须对截图进行降采样以减小其大小，以避免克劳德的上下文窗口问题。这使您能够向Claude提供有关网站结构和外观的上下文，从而为提高网站性能提供更准确和相关的建议。网络爬虫的实现在 src/analytics_service/crawler.py 文件。

alt text

安装指南

先决条件

• 安装uv： pip install uv

1. Claude桌面配置

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

- MacOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %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_USENAME和UMAMI_PASSWORD，替换 yourUmamiUsername 和 yourUmamiPassword 使用您的Umami帐户凭据。 对于UMAMI_TEAM_ID，替换 yourUmamiTeamId 使用您要分析的团队的ID。

1. 打开克劳德桌面

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

alt text

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

alt text

如何使用服务器

入门指南

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

alt text

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

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

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

alt text

自然语言用法

为了获得更可定制的体验，您可以直接与Claude交谈，并指定自己的要求，例如您想在仪表板上看到什么数据以及您想使用什么可视化。此外，您可以分析用户旅程，以确定具体的痛点，并从您的网站添加截图，为Claude提供额外的上下文

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

alt text

创建自己的提示

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

1. 定义您的提示结构

创建一个提示定义，其中包括：

- name：提示的唯一标识符 - description：明确解释提示的作用 - arguments：提示所需的输入参数列表

将此添加到 list_prompts() 功能在 src/analytics_service/server.py:

示例结构：

   @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
                   }
               ]
           }
       ]

1. 实施提示

在中添加您的提示处理逻辑 get_prompt() 功能在 src/analytics_service/server.py:

   @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 type提供了几个重要的好处：

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

下面是一个显示不同角色和内容类型的示例：

   "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"
               }
           }
       }
   ]

对于大多数提示，具有用户角色的文本类型绰绰有余，并允许Claude在响应中拥有更多的控制权和创造力。然而，对于更复杂的工作流程，具有不同角色和类型的多条消息允许更结构化的对话流和更多的用户对响应的控制。

1. 创建提示的最佳实践

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