MCP Server for Perses

Perses 的 MCP 服务

概述

Perses MCP 服务是一个本地 Model Context Protocol (MCP) 服务，可让大模型宿主（OpenCode、Claude Desktop、VS Code、Cursor）以标准化方式与 Perses 应用交互。

演示

OpenCode

https://github.com/user-attachments/assets/03706209-abef-47f2-8067-67c723537750

入门

先决条件

• 一个正在运行的 Perses 实例
• MCP 服务二进制文件——从发布页面下载，解压并赋予其可执行权限：

  chmod +x /path/to/perses-mcp-server
  

1. 创建配置文件

创建一个 YAML 配置文件（例如 perses-mcp-config.yaml）。有关各身份验证方法的详情，请参阅身份验证。

# MCP transport mode: "stdio" or "http"
transport: stdio

# Address to listen on for HTTP transport (e.g., ":8000")
listen_address: ":8000"

# Restrict the server to read-only operations
read_only: false

# Comma-separated list of resources to register (if empty, all resources are registered)
resources: ""

# Perses server connection configuration
perses_server:
  url: "http://localhost:8080"

  # Authentication (choose one method):
  # It is recommended to use environment variables for sensitive values.
  # Refer the "Environment Variables" section.

  # Option 1: Basic authentication (login/password)
  # native_auth:
  #   login: "admin"
  #   password: "password"

  # Option 2: Bearer token (e.g., from `percli whoami --show-token`)
  # authorization:
  #   type: Bearer
  #   credentials: "<YOUR_TOKEN>"
  #   # credentials_file: "/path/to/token/file"  # Alternative: read token from file

  # TLS configuration (optional)
  # tls_config:
  #   ca_file: "/path/to/ca.pem"
  #   insecure_skip_verify: false

说明

配置值按以下顺序解析（后者优先）：内置默认值 < YAML 配置文件 < 环境变量。

可用资源

resources 字段接受以下资源名称（不区分大小写，以逗号分隔）：

环境变量

YAML 文件中的配置值可以使用带有 PERMCP_ 前缀的环境变量覆盖。变量名由 YAML 键全部转为大写，并用 _ 连接嵌套键生成。

例如，YAML 路径 perses_server.native_auth.password 会转换为 PERMCP_PERSES_SERVER_NATIVE_AUTH_PASSWORD。

这对于密码和令牌等敏感值尤其有用，可避免将它们存储在配置文件中。

有关环境变量如何覆盖配置文件的详情，请参阅 Perses 配置文档。

2. 将 MCP 服务添加到客户端

标准配置适用于大多数客户端：

{
  "mcpServers": {
    "perses-mcp": {
      "command": "<ABSOLUTE_PATH_TO_PERSES_MCP_BINARY>",
      "args": [
        "--config",
        "<ABSOLUTE_PATH_TO_CONFIG_YAML>"
      ]
    }
  }
}

提示

请将敏感的身份验证值作为环境变量传递，而不是存储在配置文件中：

基本身份验证：PERMCP_PERSES_SERVER_NATIVE_AUTH_LOGIN 和 PERMCP_PERSES_SERVER_NATIVE_AUTH_PASSWORD

Bearer 令牌：PERMCP_PERSES_SERVER_AUTHORIZATION_CREDENTIALS

完整列表请参阅环境变量。

{
  "mcp": {
    "perses": {
      "command": [
        "<ABSOLUTE_PATH_TO_PERSES_MCP_BINARY>",
        "--config",
        "<ABSOLUTE_PATH_TO_CONFIG_YAML>"
      ],
      "environment": {
        "PERMCP_PERSES_SERVER_NATIVE_AUTH_LOGIN": "{env:PERMCP_PERSES_SERVER_NATIVE_AUTH_LOGIN}",
        "PERMCP_PERSES_SERVER_NATIVE_AUTH_PASSWORD": "{env:PERMCP_PERSES_SERVER_NATIVE_AUTH_PASSWORD}"
      },
      "enabled": true,
      "type": "local"
    }
  }
}

claude mcp add --transport stdio \
  --env PERMCP_PERSES_SERVER_NATIVE_AUTH_LOGIN=<YOUR_LOGIN> \
  --env PERMCP_PERSES_SERVER_NATIVE_AUTH_PASSWORD=<YOUR_PASSWORD> \
  perses-mcp -- <ABSOLUTE_PATH_TO_PERSES_MCP_BINARY> --config <ABSOLUTE_PATH_TO_CONFIG_YAML>

{
  "mcpServers": {
    "perses-mcp": {
      "command": "<ABSOLUTE_PATH_TO_PERSES_MCP_BINARY>",
      "args": [
        "--config",
        "<ABSOLUTE_PATH_TO_CONFIG_YAML>"
      ],
      "env": {
        "PERMCP_PERSES_SERVER_NATIVE_AUTH_LOGIN": "<YOUR_LOGIN>",
        "PERMCP_PERSES_SERVER_NATIVE_AUTH_PASSWORD": "<YOUR_PASSWORD>"
      }
    }
  }
}

{
  "servers": {
    "perses-mcp": {
      "command": "<ABSOLUTE_PATH_TO_PERSES_MCP_BINARY>",
      "args": [
        "--config",
        "<ABSOLUTE_PATH_TO_CONFIG_YAML>"
      ],
      "env": {
        "PERMCP_PERSES_SERVER_NATIVE_AUTH_LOGIN": "<YOUR_LOGIN>",
        "PERMCP_PERSES_SERVER_NATIVE_AUTH_PASSWORD": "<YOUR_PASSWORD>"
      }
    }
  }
}

Streamable HTTP 模式

Streamable HTTP 模式允许 MCP 服务通过 HTTP 与大模型宿主通信。这适用于远程托管，或允许多个客户端连接到同一个服务实例。

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

在配置文件中设置 transport: http：

transport: http
listen_address: ":8000"
perses_server:
  url: "http://localhost:8080"
  native_auth:
    login: "admin"
    password: "password"

然后将 MCP 客户端指向 HTTP 端点：

{
  "servers": {
    "perses-http": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

身份验证

有两种方式可以通过 Perses 实例对 MCP 服务进行身份验证。在配置文件的 perses_server 下添加相应配置块。

基本身份验证（用户名/密码）

直接使用 Perses 用户名和密码：

native_auth:
  login: "your-username"
  password: "your-password"

Bearer 令牌（通过 percli）

1. 安装 percli 并登录 Perses 服务：

percli login <PERSES_SERVER_URL>

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

2. 登录成功后，获取令牌：

percli whoami --show-token

3. 在配置文件中使用该令牌：

authorization:
  type: Bearer
  credentials: "<YOUR_TOKEN>"

警告

Bearer 令牌会根据 Perses 服务的 access_token_ttl 设置自动过期（默认值：15 分钟）。你可以在 Perses 应用的配置中更改此设置。

命令行用法

perses-mcp-server --config /path/to/config.yaml

工具

说明

以只读模式运行时（配置中设为 read_only: true），仅可使用检索信息的工具。只读模式下会禁用所有写入操作（创建、更新、删除）。

项目

仪表板

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

临时仪表板

临时仪表板是带有 TTL（生存时间）的临时仪表板。过期后会自动清理。

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

数据源

查询数据源

perses_query_project_datasource 和 perses_query_global_datasource 会通过 Perses 代理将 HTTP 请求转发到已配置的数据源后端。这意味着：

• 凭据会自动注入 — Perses 中配置的数据源密钥（Bearer 令牌、Basic 认证、OAuth）会在服务端应用；这些凭据绝不会暴露给工具调用方。
• 会强制执行允许访问的端点 — 只能访问数据源 allowedEndpoints 配置中允许的端点。
• method 默认为 GET。仅接受 GET 和 POST。
• path 是相对于数据源的端点路径，例如，Prometheus 使用 /api/v1/query_range，Loki 使用 /loki/api/v1/query_range。
• query_params 是由键值字符串对组成的对象，会作为查询字符串参数附加。
• body 是原始字符串正文（JSON 或 application/x-www-form-urlencoded）。提供正文时，Content-Type 默认为 application/json。
• headers 允许传递额外的请求标头。工具输入始终禁止使用 Authorization 标头；请使用 Perses 密钥进行身份验证。
• 响应正文上限为 1 MiB，以避免超出大模型上下文限制。

示例 — 通过全局数据源执行 Prometheus 瞬时查询：

{
  "datasource_name": "my-prometheus",
  "method": "POST",
  "path": "/api/v1/query",
  "query_params": {
    "query": "up",
    "time": "2024-01-01T00:00:00Z"
  }
}

示例 — 通过项目数据源执行 Prometheus 范围查询：

{
  "project": "my-project",
  "datasource_name": "my-prometheus",
  "method": "POST",
  "path": "/api/v1/query_range",
  "query_params": {
    "query": "rate(http_requests_total[5m])",
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-01T01:00:00Z",
    "step": "60"
  }
}

角色

插件

变量

本地开发

从源代码构建

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

make build

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

许可证

代码采用 Apache 2.0 许可证。