Perses MCP Server 使用说明

项目简介

Perses MCP Server 是一个实现了 Model Context Protocol (MCP) 的服务器，专为 Perses 监控系统设计。它作为 LLM (如 Claude Desktop, VS Code with GitHub Copilot) 和 Perses 应用之间的桥梁，允许 LLM 通过标准化的 MCP 协议访问 Perses 的项目、仪表盘、数据源和变量等资源，从而为 LLM 提供丰富的监控上下文信息，增强其在监控和运维场景下的能力。

主要功能点

资源访问: 通过 MCP 协议向 LLM 客户端提供对 Perses 项目、仪表盘、数据源和变量等监控资源的访问能力。
工具集成: 内置了一系列预定义的工具，允许 LLM 客户端查询和获取 Perses 监控数据，例如：
- 'perses_list_projects': 列出所有 Perses 项目。
- 'perses_list_dashboards': 列出指定项目下的所有仪表盘。
- 'perses_list_global_datasources': 列出所有全局数据源。
- 'perses_list_datasources': 列出指定项目下的数据源。
- 'perses_list_global_variables': 列出所有全局变量。
- 'perses_list_variables': 列出指定项目下的变量。
标准化协议: 基于 MCP 协议与 LLM 客户端通信，确保与支持 MCP 协议的 LLM 应用无缝集成。
易于集成: 提供了详细的 Claude Desktop 和 VS Code GitHub Copilot 集成指南，方便用户快速配置和使用。

安装步骤

安装 percli: 确保已安装 Perses 命令行工具 'percli'，用于与 Perses 服务器交互。请参考 percli 官方文档进行安装。
获取 Perses 认证 Token:
- 使用 'percli login <PERSES_SERVER_URL>' 命令登录您的 Perses 服务器。
- 使用 'percli whoami --show-token' 命令获取您的 Perses 认证 Token。
- 复制 Token 值，后续配置 MCP 服务器时需要使用。
下载 Perses MCP Server: 从 GitHub 仓库下载 'mcp-server' 项目的编译好的二进制文件或自行编译。

服务器配置

MCP 客户端配置 (以 Claude Desktop 和 VS Code 为例):

Claude Desktop 配置:

打开 Claude Desktop 配置文件 ('claude_desktop_config.json')，通常位于：

macOS: '~/Library/Application Support/Claude/claude_desktop_config.json'
Windows: '%APPDATA%\Claude\claude_desktop_config.json'
Linux: '~/.config/Claude/claude_desktop_config.json'

在 'mcpServers' 字段中添加 'perses-mcp' 服务器配置：

{
  "mcpServers": {
    "perses-mcp": {
      "command": "<Perses MCP Server 可执行文件的绝对路径>",  //  **[必填]**：替换为 Perses MCP Server 可执行文件的绝对路径
      "args": [
        "--perses-server-url",
        "<Perses Server URL>"    // **[必填]**：替换为您的 Perses 服务器 URL，例如 http://localhost:8080
      ],
      "env": {
        "PERSES_TOKEN": "<您的 Perses Token>"  // **[必填]**：替换为您之前获取的 Perses 认证 Token
      }
    }
  }
}

VS Code GitHub Copilot 配置:

打开 VS Code 用户设置 (JSON)，在 'servers' 字段中添加 'perses-mcp' 服务器配置：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "perses-token",
      "description": "PERSES_TOKEN to connect with Perses Application",
      "password": true
    }
  ],
  "servers": {
    "perses-mcp": {
      "command": "<Perses MCP Server 可执行文件的绝对路径>",  // **[必填]**：替换为 Perses MCP Server 可执行文件的绝对路径
      "args": [
        "--perses-server-url",
        "http://localhost:8080"   // **[可选]**：您的 Perses 服务器 URL，默认为 http://localhost:8080，可以根据实际情况修改
      ],
      "env": {
        "PERSES_TOKEN": "${input:perses-token}" // 使用输入参数 'perses-token' 获取 Perses 认证 Token，您需要在VS Code中输入该 Token
      }
    }
  }
}

注意:

'<Perses MCP Server 可执行文件的绝对路径>': 需要替换为实际的 'mcp-server' 可执行文件在您系统中的绝对路径。
'<Perses Server URL>': 需要替换为您的 Perses 后端服务器的 URL。
'<您的 Perses Token>' (Claude Desktop): 需要替换为您之前获取的 Perses 认证 Token。
'${input:perses-token}' (VS Code): VS Code 会提示您输入 'PERSES_TOKEN'，您需要输入之前获取的 Perses 认证 Token。

基本使用方法

配置完成后，当您在 Claude Desktop 或 VS Code 中与 LLM 交互时，LLM 就可以通过 MCP 协议调用 Perses MCP Server 提供的工具，例如：

您可以指示 LLM 列出 Perses 中的所有项目，LLM 将调用 'perses_list_projects' 工具并返回项目列表。
您可以要求 LLM 查询特定项目的仪表盘，LLM 将调用 'perses_list_dashboards' 工具，并需要您提供项目名称作为参数。

LLM 如何具体调用和使用这些工具取决于 LLM 客户端的实现和用户界面的设计。请参考您使用的 LLM 客户端的文档，了解如何利用 MCP 服务器提供的功能。

运行 Perses MCP Server (开发者/高级用户):

如果您需要自行运行 Perses MCP Server，可以执行以下命令：

./mcp-server --perses-server-url <Perses Server URL> --log-level info

'--perses-server-url': 指定 Perses 后端服务器的 URL (默认为 'http://localhost:8080')。
'--log-level': 设置日志级别 (默认为 'info'，可选 'debug', 'warn', 'error')。

确保 'PERSES_TOKEN' 环境变量已设置，或者在运行命令前使用 'export PERSES_TOKEN=<您的 Perses Token>' 设置环境变量。

关键词