Overview

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

Demo

Claude Desktop

https://github.com/user-attachments/assets/87137515-1b45-442d-a4c9-68f460a1ba4c

VS Code with GitHub Copilot

https://github.com/user-attachments/assets/b80c354a-8006-4e1f-b7f4-e123002f7dc3

Usage

Pre-requisites

• percli
• PERSES_TOKEN

Obtaining Your Perses Authentication Token

1. Login to your Perses server using the percli command line tool:

percli login <PERSES_SERVER_URL>

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

Or percli login http://localhost:8080 if you are running perses/perses locally from the source code or from the perses image.

2. After successful login, retrieve your token:

percli whoami --show-token

Copy the token to use in your MCP server configuration.

WARNING: Your login will automatically expire in 15 minutes. If you want to extend the token duration, you can change the access_token_ttl setting in the Perses app configuration, then restart the app (if running locally) or rebuild the Docker image.

Integration with Claude Desktop

To add this MCP server to Claude Desktop:

1. 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 easily access this file via the Claude Desktop app by navigating to Claude > Settings > Developer > Edit Config.

2. Get the binary

You have two options to obtain the MCP server binary:

Option A: Download from Releases (Recommended)

1. Go to the releases page
2. Download the appropriate binary for your operating system and architecture
3. Extract the binary to a location of your choice
4. Make the binary executable (on Unix-like systems):

   chmod +x /path/to/mcp-server
   

5. Copy the absolute path to the binary to use in your MCP server configuration

Option B: Build from Source

make build

This should create a bin directory which contains the binary named mcp-server. Copy the absolute path to the binary to use in your MCP server configuration.

3. Add the following JSON block to the configuration file:

{
  "mcpServers": {
    "perses-mcp": {
      "command": "<ABSOLUTE_PATH_TO_PERSES_MCP_BINARY>",
      "args": [
        "--perses-server-url",
        "<PERSES_SERVER_URL>"
        // Add "--read-only" here for read-only mode
      ],
      "env": {
        "PERSES_TOKEN": "<PERSES_TOKEN>"
      }
    }
  }
}

3. Restart Claude Desktop for the changes to take effect.

Integration with VS Code GitHub Copilot

To integrate the MCP server with VS Code GitHub Copilot, follow these steps:

1. Open User Settings (JSON) in VS Code:

   • Press Cmd + Shift + P (on macOS) or Ctrl + Shift + P (on other platforms).
   • Type Preferences: Open User Settings (JSON) and select it.

2. Add the following JSON block to the User Settings (JSON) file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "perses-token",
      "description": "PERSES_TOKEN to connect with Perses Application",
      "password": true
    }
  ],
  "servers": {
    "perses-mcp": {
      "command": "<ABSOLUTE_PATH_TO_PERSES_MCP_BINARY>",
      "args": [
        "--perses-server-url",
        "http://localhost:8080"
        // Add "--read-only" here for read-only mode
      ],
      "env": {
        "PERSES_TOKEN": "${input:perses-token}"
      }
    }
  }
}

1. Optionally, create a file named .vscode/mcp.json in your workspace and add the same JSON block. This allows you to share the configuration with others.

Tools

Projects

Tool	Description	Required Parameters
perses_list_projects	List all projects	-
perses_get_project_by_name	Get a project by name	project
perses_create_project	Create a new project	project

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, dashboard
perses_create_dashboard	Create a dashboard given a project and dashboard configuration	project, dashboard

For dashboard configuration, see Perses Dashboards

Datasources

Tool	Description	Required Parameters	Optional Parameters
perses_list_global_datasources	List all global datasources	-	-
perses_list_datasources	List all datasources for a specific project	project	-
perses_get_global_datasource_by_name	Get a global datasource by name	datasource	-
perses_get_project_datasource_by_name	Get a project datasource by name	project, datasource	-
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

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	role
perses_list_global_role_bindings	List all global role bindings	-
perses_get_global_role_binding_by_name	Get a global role binding by name	roleBinding
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, role
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, roleBinding

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	variable
perses_list_variables	List all variables for a specific project	project
perses_get_project_variable_by_name	Get a project variable by name	project, variable
perses_create_project_variable	Create a project level variable	name, project

License

The code is licensed under an Apache 2.0 license.