https://github.com/perses/mcp-server
MCP Server for Perses
https://github.com/perses/mcp-server
Last synced: 2 months ago
JSON representation
MCP Server for Perses
- Host: GitHub
- URL: https://github.com/perses/mcp-server
- Owner: perses
- License: apache-2.0
- Created: 2025-04-22T10:15:56.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-07-30T15:27:49.000Z (2 months ago)
- Last Synced: 2025-07-30T18:24:11.983Z (2 months ago)
- Language: Go
- Homepage:
- Size: 473 KB
- Stars: 12
- Watchers: 3
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
MCP Server for Perses
> [!WARNING]
> This MCP Server is currently in **beta**. Features and tools may change, and stability is not guaranteed. Feedback and contributions are most welcome!
## Overview
The Perses MCP Server is a local [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) 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](https://perses.dev/perses/docs/cli/)
- `PERSES_TOKEN`
#### Obtaining Your Perses Authentication Token
1. Login to your Perses server using the `percli` command line tool:
```bash
percli login
```
For example, `percli login https://demo.perses.dev`.
Or `percli login http://localhost:8080` if you are running [perses/perses](https://github.com/perses/perses) locally from the source code or from the perses image.
2. After successful login, retrieve your token:
```bash
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](https://perses.dev/perses/docs/configuration/configuration/?h=configu), then restart the app (if running locally) or rebuild the Docker image.
### Integration with Claude Desktop
To add this MCP server to [Claude Desktop](https://claude.ai/download):
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](https://github.com/perses/mcp-server/releases)
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):
```bash
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**
```bash
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:
```json
{
"mcpServers": {
"perses-mcp": {
"command": "",
"args": [
"--perses-server-url",
""
],
"env": {
"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:
```json
{
"inputs": [
{
"type": "promptString",
"id": "perses-token",
"description": "PERSES_TOKEN to connect with Perses Application",
"password": true
}
],
"servers": {
"perses-mcp": {
"command": "",
"args": [
"--perses-server-url",
"http://localhost:8080"
],
"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` |
### 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](https://github.com/perses/perses/blob/main/docs/api/dashboard.md)
### Datasources
| Tool | Description | Required 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` |
### 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` |
## License
The code is licensed under an [Apache 2.0](./LICENSE) license.