味美 MCP 服务器

Name: 味美 MCP 服务器
Author: jakeyShakey

作者：jakeyShakey6 星标更新：2025-03-06

安装使用来源：spider==github.com

项目介绍

Umami Analytics MCP Server

这是一个基于模型上下文协议（MCP）的服务器，通过提供来自Umami的网站分析数据来增强Claude的功能。该服务器允许Claude分析用户行为、跟踪网站性能并提供数据驱动的见解。

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

alt text

功能概述

此服务器连接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文件中。

alt text

安装指南

先决条件

安装uv: pip install uv

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。
打开Claude Desktop

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

alt text

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

alt text

如何使用服务器

开始使用

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

alt text

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

您想要分析的网站名称
分析的起始和结束日期
网站的时区

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

alt text

自然语言使用

对于更灵活的体验，您可以直接与Claude交谈并指定自己的需求，例如您希望在仪表板上看到哪些数据以及您想使用哪些可视化。此外，您可以分析用户旅程以确定具体痛点，并添加来自您站点的截图以给Claude提供更多上下文。

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

alt text

创建您自己的提示

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

定义您的提示结构 创建一个包含以下内容的提示定义：

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

实现提示 在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"模拟用户输入或问题
- 使用"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": "分析以下日志文件和代码，查找潜在问题。"
        }
    },
    {
        "role": "user",
        "content": {
            "type": "resource",
            "resource": {
                "uri": "logs://recent",
                "text": "[2024-03-14 15:32:11] 错误：连接超时",
                "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在其响应中有更多的控制和创造力。然而，对于更复杂的流程，具有不同角色和类型的多条消息允许更结构化的对话流程和更多的用户对响应的控制。
创建提示的最佳实践
- 让您的提示集中且具体
- 包括明确的参数验证要求
- 使用描述性名称命名参数
- 在参数描述中包含示例值
- 结构化提示模板以有效指导Claude
- 考虑错误处理和边缘情况
- 使用各种输入测试提示