MCP Server for Perses

Overview

The Perses MCP Server is a local Model Context Protocol (MCP) Server that enables the LLM hosts (OpenCode, Claude Desktop, VS Code, Cursor) to interact with the Perses Application in a standardized way.

Demo

OpenCode

Getting Started

Prerequisites

• A running Perses instance
• The MCP server binary — download from the releases page, extract it, and make it executable:

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

1. Create a configuration file

Create a YAML configuration file (e.g., perses-mcp-config.yaml). See Authentication for details on each auth method.

# 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

Note

Configuration values are resolved in this order (later wins): built-in defaults < YAML configuration file < environment variables.

Available Resources

The resources field accepts the following resource names (case-insensitive, comma-separated):

Environment Variables

Configuration values in the YAML file can be overridden using environment variables with the PERMCP_ prefix. The variable name is derived by uppercasing each YAML key and joining nested keys with _.

For example, the YAML path perses_server.native_auth.password becomes PERMCP_PERSES_SERVER_NATIVE_AUTH_PASSWORD.

This is particularly useful for sensitive values like passwords and tokens that should not be stored in the config file.

For more details about how environment variables override the configuration file, see the Perses Configuration docs.

2. Add the MCP server to your client

Standard config works in most clients:

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

Tip

Pass sensitive auth values as environment variables instead of storing them in the config file:

Basic auth: PERMCP_PERSES_SERVER_NATIVE_AUTH_LOGIN and PERMCP_PERSES_SERVER_NATIVE_AUTH_PASSWORD

Bearer token: PERMCP_PERSES_SERVER_AUTHORIZATION_CREDENTIALS

See Environment Variables for the full list.

{
  "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 Mode

The Streamable HTTP mode allows the MCP server to communicate with LLM hosts over HTTP. This is useful for remote hosting or allowing multiple clients to connect to the same server instance.

For more details, see the MCP Protocol Specification docs.

Set transport: http in your configuration file:

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

Then point your MCP client to the HTTP endpoint:

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

Authentication

There are two ways to authenticate the MCP server with your Perses instance. Add the relevant block under perses_server in your configuration file.

Basic Authentication (Username/Password)

Use your Perses username and password directly:

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

Bearer Token (via percli)

1. Install percli and login to your Perses server:

percli login <PERSES_SERVER_URL>

For example, percli login https://demo.perses.dev

2. After successful login, retrieve your token:

percli whoami --show-token

3. Use the token in your configuration file:

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

Warning

The bearer token automatically expires based on the access_token_ttl setting (default: 15 minutes) of the Perses server. You can change this in the Perses app configuration.

Command-Line Usage

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

Tools

Note

When running in read-only mode (read_only: true in config), only tools that retrieve information are available. All write operations (create, update, delete) are disabled in read-only mode.

Projects

Dashboards

For dashboard configuration, see Perses Dashboards

Ephemeral Dashboards

Ephemeral dashboards are temporary dashboards with a TTL (time-to-live). They are automatically cleaned up after expiry.

For ephemeral dashboard configuration, see Perses EphemeralDashboard

Datasources

Querying Datasources

perses_query_project_datasource and perses_query_global_datasource forward HTTP requests to a configured datasource backend through the Perses proxy. This means:

• Credentials are automatically injected — datasource secrets configured in Perses (Bearer tokens, Basic auth, OAuth) are applied server-side; they are never exposed to the tool caller.
• Allowed endpoints are enforced — only endpoints permitted by the datasource's allowedEndpoints configuration are reachable.
• method defaults to GET. Only GET and POST are accepted.
• path is the datasource-relative endpoint path, e.g. /api/v1/query_range for Prometheus or /loki/api/v1/query_range for Loki.
• query_params is an object of key/value string pairs appended as query string parameters.
• body is a raw string body (JSON or application/x-www-form-urlencoded). Content-Type defaults to application/json when a body is provided.
• headers allows passing additional request headers. The Authorization header is always blocked in tool input; use Perses secrets for authentication.
• Response bodies are capped at 1 MiB to avoid exceeding LLM context limits.

Example — Prometheus instant query via a global datasource:

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

Example — Prometheus range query via a project datasource:

{
  "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"
  }
}

Roles

Plugins

Variables

Local Development

Build from Source

If you want to build the MCP server from source code (for development or contribution purposes), run the following command from the source code root directory:

make build

This creates a bin directory containing the binary named mcp-server. Copy the absolute path to the binary to use in your MCP server configuration.

License

The code is licensed under an Apache 2.0 license.