MCP服务器

Name: MCP服务器
Author: perses

作者：perses15 星标更新：2025-11-23

项目介绍

<div align="center"> <img src="https://raw.githubusercontent.com/perses/perses/main/docs/images/perses_logo_cropped.svg" alt="Perses"> <h1 align="center">Perses 的 MCP 服务器</h1> </div>

[!WARNING]
此 MCP 服务器目前处于测试版。功能和工具可能会发生变化，并且稳定性无法保证。欢迎提供反馈和贡献！

概述

Perses MCP 服务器是一个本地的模型上下文协议 (MCP) 服务器，它使 LLM 主机（如 Claude Desktop、VS Code、Cursor）能够以标准化的方式与 Perses 应用程序进行交互。

示例

<details open> <summary>Claude Desktop</summary>

https://github.com/user-attachments/assets/87137515-1b45-442d-a4c9-68f460a1ba4c

</details> <details> <summary>带有 GitHub Copilot 的 VS Code</summary>

https://github.com/user-attachments/assets/b80c354a-8006-4e1f-b7f4-e123002f7dc3

</details>

先决条件

percli
PERSES_TOKEN

获取您的 Perses 认证令牌

使用 percli 命令行工具登录到您的 Perses 服务器：

percli login <PERSES_SERVER_URL>

例如，percli login https://demo.perses.dev。

或者如果您在本地从源代码或 perses 镜像运行 perses/perses，则使用 percli login http://localhost:8080。

登录成功后，获取您的令牌：

percli whoami --show-token

复制该令牌以用于您的 MCP 服务器配置。

警告：您的登录将在 15 分钟后自动过期。如果您想延长令牌的有效时间，可以在 Perses 应用程序的配置中更改 access_token_ttl 设置，然后重新启动应用程序（如果是在本地运行）或重建 Docker 镜像。

下载 MCP 服务器二进制文件

从 Releases 下载

转到发布页面
下载适合您操作系统的二进制文件
将二进制文件解压到您选择的位置
在类 Unix 系统上，使二进制文件可执行：
```
chmod +x /path/to/mcp-server
```
复制二进制文件的绝对路径（例如，/path/to/mcp-server），以用于您的 MCP 服务器配置

传输模式

Perses MCP 服务器支持两种传输模式：STDIO 模式和流式 HTTP 模式。

STDIO 模式

在这种模式下，MCP 服务器通过标准输入和输出（STDIO）与 LLM 主机通信。

更多详情，请参阅 MCP 协议规范文档。

<details> <summary>在 Claude Desktop 中安装</summary>

https://github.com/user-attachments/assets/b80c354a-8006-4e1f-b7f4-e123002f7dc3

要将此 MCP 服务器添加到 Claude Desktop：

创建或编辑 Claude Desktop 配置文件：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json

您可以通过 Claude Desktop 应用程序导航至 Claude > 设置 > 开发者 > 编辑配置 来轻松访问此文件。

向配置文件添加以下 JSON 块：

{
  "mcpServers": {
    "perses-mcp": {
      "command": "<ABSOLUTE_PATH_TO_PERSES_MCP_BINARY>",
      "args": [
        "--perses-server-url",
        "<PERSES_SERVER_URL>"
        // 在此处添加 "--read-only" 以启用只读模式
      ],
      "env": {
        "PERSES_TOKEN": "<PERSES_TOKEN>"
      }
    }
  }
}

重启 Claude Desktop 以使更改生效。

</details> <details> <summary>在 VS Code 中安装</summary>

向 VS Code MCP 配置文件添加以下 JSON 代码片段。更多详情，请参阅 VS Code MCP 文档。

{
  "inputs": [
    {
      "type": "promptString",
      "id": "perses-token",
      "description": "连接 Perses 应用程序的 PERSES_TOKEN",
      "password": true
    }
  ],
  "servers": {
    "perses-mcp": {
      "command": "<ABSOLUTE_PATH_TO_PERSES_MCP_BINARY>",
      "args": [
        "--perses-server-url",
        "http://localhost:8080"
        // 在此处添加 "--read-only" 以启用只读模式
      ],
      "env": {
        "PERSES_TOKEN": "${input:perses-token}"
      }
    }
  }
}

</details>

流式 HTTP 模式

流式 HTTP 模式允许 MCP 服务器通过 HTTP 与 LLM 主机通信，类似于常规的 Web API。这种模式特别适用于：

远程托管：在云实例或远程服务器上部署 MCP 服务器
多个客户端：允许多个 LLM 主机连接到同一个服务器实例

更多详情，请参阅 MCP 协议规范文档。

在启动 MCP 服务器之前，设置您的 Perses 认证令牌：

export PERSES_TOKEN=<YOUR_PERSES_TOKEN>

运行以下命令以在流式 HTTP 模式下启动 MCP 服务器：

/path/to/mcp-server --transport streamable-http --perses-server-url <PERSES_SERVER_URL> --port 8000

<details> <summary>在 VS Code 中安装</summary> 向 VS Code MCP 配置文件添加以下 JSON 代码片段。更多详情，请参阅 [VS Code MCP 文档](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)。

{
  "servers": {
    "perses-http": {
      "type": "http",
      "url": "http://localhost:<port>/mcp"
    }
  }
}

</details>

命令行标志

Perses MCP 服务器支持多个命令行标志来自定义其行为：

标志	默认值	描述
`--perses-server-url`	`http://localhost:8080`	Perses 后端服务器的 URL
`--log-level`	`info`	日志级别（选项：`debug`，`info`，`warn`，`error`）
`--transport`	`stdio`	MCP 协议传输机制（选项：`stdio`，`streamable-http`）
`--port`	`8000`	运行 HTTP 流式服务器的端口（仅在使用 `streamable-http` 传输时使用）
`--read-only`	`false`	限制服务器为只读操作

本地开发

从源代码构建

如果您想从源代码构建 MCP 服务器（用于开发或贡献目的），请从源代码根目录运行以下命令：

make build

这应该会创建一个 bin 目录，其中包含名为 mcp-server 的二进制文件。复制该二进制文件的绝对路径，以用于您的 MCP 服务器配置。

工具

[!NOTE]
当以只读模式运行（--read-only 标志）时，只有检索信息的工具可用。写入操作如 create_project，create_dashboard，create_global_datasource，update_global_datasource 和 create_project_variable 在只读模式下被禁用。

项目

工具	描述	必需参数
`perses_list_projects`	列出所有项目	-
`perses_get_project_by_name`	通过名称获取项目	`project`
`perses_create_project`	创建新项目	`project`

仪表板

工具	描述	必需参数
`perses_list_dashboards`	列出特定项目的所有仪表板	`project`
`perses_get_dashboard_by_name`	通过名称获取项目中的仪表板	`project`，`dashboard`
`perses_create_dashboard`	给定项目和仪表板配置创建仪表板	`project`，`dashboard`

有关仪表板配置，请参阅 Perses 仪表板

数据源

工具	描述	必需参数	可选参数
`perses_list_global_datasources`	列出所有全局数据源	-	-
`perses_list_datasources`	列出特定项目的全部数据源	`project`	-
`perses_get_global_datasource_by_name`	通过名称获取全局数据源	`datasource`	-
`perses_get_project_datasource_by_name`	通过名称获取项目数据源	`project`，`datasource`	-
`perses_create_global_datasource`	创建新的全局数据源	`name`，`type`，`url`	`display_name`，`proxy_type`
`perses_update_global_datasource`	更新现有的全局数据源	`name`，`type`，`url`	`display_name`，`proxy_type`

角色

工具	描述	必需参数
`perses_list_global_roles`	列出所有全局角色	-
`perses_get_global_role_by_name`	通过名称获取全局角色	`role`
`perses_list_global_role_bindings`	列出所有全局角色绑定	-
`perses_get_global_role_binding_by_name`	通过名称获取全局角色绑定	`roleBinding`
`perses_list_project_roles`	列出特定项目的全部角色	`project`
`perses_get_project_role_by_name`	通过名称获取项目角色	`project`，`role`
`perses_list_project_role_bindings`	列出项目的全部角色绑定	`project`
`perses_get_project_role_binding_by_name`	通过名称获取项目角色绑定	`project`，`roleBinding`

插件

工具	描述	必需参数
`perses_list_plugins`	列出所有插件	-

变量

工具	描述	必需参数
`perses_list_global_variables`	列出所有全局变量	-
`perses_get_global_variable_by_name`	通过名称获取全局变量	`variable`
`perses_list_variables`	列出特定项目的全部变量	`project`
`perses_get_project_variable_by_name`	通过名称获取项目变量	`project`，`variable`
`perses_create_project_variable`	创建项目级别的变量	`name`，`project`

许可证

代码采用 Apache 2.0 许可证。