Server

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

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.

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

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>

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.

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.

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

1. After successful login, retrieve your token:

percli whoami --show-token

1. 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. Write operations like create_project, create_dashboard, create_global_datasource, update_global_datasource, and create_project_variable are disabled in read-only mode.

Projects

Dashboards

For dashboard configuration, see Perses Dashboards

Datasources

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.