使用说明

项目简介

Perses MCP Server 是一个本地 MCP 服务器，它允许 LLM 客户端（如 Claude Desktop、VS Code）以标准化的方式与 Perses 应用进行交互。它通过 MCP 协议，将 Perses 的项目、仪表盘、数据源和变量等资源以工具的形式暴露给 LLM 客户端，从而扩展 LLM 的上下文理解和操作能力。

主要功能点

提供多种工具，用于列出 Perses 的项目、仪表盘、全局数据源、项目数据源、全局变量和项目变量。
基于 MCP 协议，与 LLM 客户端进行标准化通信。
使用 Stdio 作为传输协议。

安装步骤

安装 percli 和配置 PERSES_TOKEN: 确保已安装 percli 命令行工具，并已登录 Perses 服务器并获取 'PERSES_TOKEN' 环境变量。

percli login <PERSES_SERVER_URL>
percli whoami --show-token
export PERSES_TOKEN=<your_token>

下载或编译 perses-mcp: 从仓库下载预编译的 'perses-mcp' 程序，或者自行克隆仓库并使用 'go build' 命令编译 'main.go' 文件。
启动 perses-mcp 服务器: 在终端中运行编译或下载得到的 'perses-mcp' 可执行文件。

服务器配置

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' 字段中添加以下 JSON 配置块：

{
  "mcpServers": {
    "perses-mcp": {
      "command": "<perses-mcp 服务器程序绝对路径>",
      "args": [
        "--perses-server-url",
        "<Perses 服务器 URL>"
      ],
      "env": {
        "PERSES_TOKEN": "<Perses 认证 Token>"
      }
    }
  }
}

VS Code GitHub Copilot 配置:

打开 VS Code 的用户设置 (JSON) ('settings.json')，添加以下 JSON 配置块：

{
  "servers": {
    "perses-mcp": {
      "command": "<perses-mcp 服务器程序绝对路径>",
      "args": [
        "--perses-server-url",
        "http://localhost:8080"
      ],
      "env": {
        "PERSES_TOKEN": "${input:perses-token}"
      }
    }
  },
  "inputs": [
    {
      "id": "perses-token",
      "type": "promptString",
      "description": "PERSES_TOKEN to connect with Perses Application",
      "password": true
    }
  ]
}

配置说明:

'<perses-mcp 服务器程序绝对路径>': 替换为 'perses-mcp' 可执行文件的实际路径。
'<Perses 服务器 URL>': 替换为你的 Perses 后端服务地址，例如 'http://localhost:8080' 或 'https://your-perses-server.com'。
'<Perses 认证 Token>': 替换为你的 Perses 认证 Token，即 'PERSES_TOKEN' 环境变量的值。

基本使用方法

确保 Perses MCP Server 已经成功启动。
在配置完成的 LLM 客户端（如 Claude Desktop 或 VS Code）中，你可以通过自然语言指令，例如 "列出所有 Perses 项目" 或 "展示项目 XYZ 的仪表盘"，来触发相应的 MCP 工具。客户端会将指令转换为 MCP 请求发送到 Perses MCP Server。
Perses MCP Server 调用相应的工具函数，从 Perses 后端获取数据，并将结果以 MCP 响应格式返回给 LLM 客户端。
LLM 客户端解析 MCP 响应，并将结果以自然语言形式呈现给用户，或者用于增强其上下文理解和生成能力。

例如，在 Claude Desktop 中，你可以尝试询问： "What are the projects in Perses?"，Claude 可能会调用 'perses_list_projects' 工具并返回项目列表。

关键词