Skip to content

perses/mcp-server

BranchesTags

Repository files navigation

Perses

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

perses-mcp-server-with-opencode.mov

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
ephemeraldashboard Ephemeral 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.

OpenCode

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

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>
Claude Desktop

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.

VS Code

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:

VS Code 
{
  "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
Flag Default Description
--config "" Path to the YAML configuration file
-log.level info Log level (options: panic, fatal, error, warning, info, debug, trace)
-log.format text Log format (options: text, json)
-log.method-trace false Include the calling method as a field in the log

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

Tool Description Required Parameters
perses_list_projects List all projects -
perses_get_project_by_name Get a project by name name
perses_create_project Create a new project project
perses_update_project Update an existing project name
perses_delete_project Delete a project name

Dashboards

Tool Description Required Parameters
perses_list_dashboards List all dashboards for a specific project project
perses_get_dashboard_by_name Get a dashboard by name for a project project, name
perses_create_dashboard Create a dashboard given a project and dashboard configuration project, dashboard
perses_update_dashboard Update an existing dashboard in a project project, dashboard
perses_delete_dashboard Delete a dashboard from a project project, name

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.

Tool Description Required Parameters
perses_list_ephemeral_dashboards List all ephemeral dashboards for a specific project project
perses_get_ephemeral_dashboard_by_name Get an ephemeral dashboard by name for a project project, name
perses_create_ephemeral_dashboard Create an ephemeral dashboard given a project and dashboard configuration project, dashboard
perses_update_ephemeral_dashboard Update an existing ephemeral dashboard in a project project, dashboard
perses_delete_ephemeral_dashboard Delete an ephemeral dashboard from a project project, name

For ephemeral dashboard configuration, see Perses EphemeralDashboard

Datasources

Tool Description Required Parameters Optional Parameters
perses_list_global_datasources List all global datasources - -
perses_get_global_datasource_by_name Get a global datasource by name name -
perses_create_global_datasource Create a new global datasource name, type, url display_name, proxy_type
perses_update_global_datasource Update an existing global datasource name, type, url display_name, proxy_type
perses_delete_global_datasource Delete a global datasource name -
perses_list_project_datasources List all datasources for a specific project project -
perses_get_project_datasource_by_name Get a project datasource by name project, name -
perses_create_project_datasource Create a new datasource in a project project, datasource -
perses_update_project_datasource Update an existing datasource in a project project, datasource -
perses_delete_project_datasource Delete a datasource from a project project, name -

Roles

Tool Description Required Parameters
perses_list_global_roles List all global roles -
perses_get_global_role_by_name Get a global role by name name
perses_create_global_role Create a new global role name, actions, scopes
perses_update_global_role Update an existing global role name, actions, scopes
perses_delete_global_role Delete a global role name
perses_list_global_role_bindings List all global role bindings -
perses_get_global_role_binding_by_name Get a global role binding by name name
perses_create_global_role_binding Create a new global role binding name, role, subjects
perses_update_global_role_binding Update an existing global role binding name, role, subjects
perses_delete_global_role_binding Delete a global role binding name
perses_list_project_roles List all roles for a specific project project
perses_get_project_role_by_name Get a project role by name project, name
perses_create_project_role Create a new project role project, name, actions, scopes
perses_update_project_role Update an existing project role project, name, actions, scopes
perses_delete_project_role Delete a project role project, name
perses_list_project_role_bindings List all role bindings for a project project
perses_get_project_role_binding_by_name Get a project role binding by name project, name
perses_create_project_role_binding Create a new project role binding project, name, role, subjects
perses_update_project_role_binding Update an existing project role binding project, name, role, subjects
perses_delete_project_role_binding Delete a project role binding project, name

Plugins

Tool Description Required Parameters
perses_list_plugins List all plugins -

Variables

Tool Description Required Parameters
perses_list_global_variables List all global variables -
perses_get_global_variable_by_name Get a global variable by name name
perses_create_global_variable Create a new global variable name, value
perses_update_global_variable Update an existing global variable name, value
perses_delete_global_variable Delete a global variable name
perses_list_project_variables List all variables for a specific project project
perses_get_project_variable_by_name Get a project variable by name project, name
perses_create_project_variable Create a project level variable name, project
perses_update_project_variable Update an existing project variable project, name, value
perses_delete_project_variable Delete a project variable project, name

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.

About

MCP Server for Perses

Resources

Readme

License

Apache-2.0 license

Code of conduct

Code of conduct
Activity
Custom properties

Stars

29 stars

Watchers

2 watching

Forks

6 forks
Report repository

Releases 3

0.1.0 / 2026-03-10 Latest
Mar 10, 2026
+ 2 releases

Packages

 
 
 

Contributors

Languages