<div align="center">

<h1 align="center">MCP Server for Perses</h1>
</div>

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

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

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):

| Resource | Description |
|---------|-------------|
| dashboard | Dashboard management tools |
| project | Project management tools |
| datasource | Project-level datasource tools |
| globaldatasource | Global datasource tools |
| role | Project-level role tools |
| globalrole | Global role tools |
| rolebinding | Project-level role binding tools |
| globalrolebinding | Global role binding tools |
| variable | Project-level variable tools |
| globalvariable | Global variable tools |
| plugin | Plugin tools |

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.

| Environment Variable | Config Path | Description |
|---------------------|-------------|-------------|
| PERMCP_TRANSPORT | transport | Transport mode |
| PERMCP_LISTEN_ADDRESS | listen_address | HTTP listen address |
| PERMCP_READ_ONLY | read_only | Read-only mode |
| PERMCP_RESOURCES | resources | Resources to register |
| PERMCP_PERSES_SERVER_URL | perses_server.url | Perses server URL |
| PERMCP_PERSES_SERVER_NATIVE_AUTH_LOGIN | perses_server.native_auth.login | Basic auth username |
| PERMCP_PERSES_SERVER_NATIVE_AUTH_PASSWORD | perses_server.native_auth.password | Basic auth password |
| PERMCP_PERSES_SERVER_AUTHORIZATION_TYPE | perses_server.authorization.type | Authorization type (e.g., Bearer) |
| PERMCP_PERSES_SERVER_AUTHORIZATION_CREDENTIALS | perses_server.authorization.credentials | Authorization token |

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.

<details>
<summary>OpenCode</summary>

Add the following to your OpenCode config under mcp. See OpenCode MCP documentation for more details.

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

<details>
<summary>Claude Code</summary>

Use the Claude Code CLI to add the Perses MCP server. See Claude Code MCP documentation for more details.

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>

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

Create or edit the Claude Desktop configuration file at:

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

You can also access this file via Claude > Settings > Developer > Edit Config.

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

Restart Claude Desktop for the changes to take effect.
</details>

<details>
<summary>VS Code</summary>

Add the following to your VS Code MCP config file. See VS Code MCP documentation for more details.

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

…