Content
# pyroscope-mcp
A read-only [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for [Grafana Pyroscope](https://grafana.com/oss/pyroscope/). Lets AI assistants query continuous profiling data — flamegraphs, hotspot functions, memory allocations, label discovery — directly from any MCP-compatible client.
> **Note:** This server is query-only. Profile ingestion is expected to be handled by your application profilers (Pyroscope SDKs, agents, or exporters).
## Tools
| Tool | Description |
|------|-------------|
| `pyroscope_render_profile` | Flamegraph + timeline data from `/pyroscope/render` |
| `pyroscope_label_names` | List all label names in a time range |
| `pyroscope_label_values` | List values for a given label (e.g. `service_name`) |
| `pyroscope_profile_types` | List available profile types (cpu, memory, goroutines…) |
| `pyroscope_series` | Fetch matching label sets for a selector |
| `pyroscope_connect_query` | Raw access to any `/querier.v1.QuerierService/*` endpoint |
## Prerequisites
- Node.js 20+
- A running Pyroscope instance (local, self-hosted, or Grafana Cloud)
## Setup
```bash
git clone https://github.com/your-org/pyroscope-mcp
cd pyroscope-mcp
npm install
npm run build
```
## Configuration
All settings are provided via environment variables:
| Variable | Default | Description |
|----------|---------|-------------|
| `PYROSCOPE_BASE_URL` | `http://localhost:4040` | Pyroscope server URL |
| `PYROSCOPE_AUTH_TOKEN` | — | Bearer token (Grafana Cloud or Azure AD) |
| `PYROSCOPE_TENANT_ID` | — | Multi-tenant org ID (`X-Scope-OrgID` header) |
| `PYROSCOPE_TIMEOUT_MS` | `30000` | Request timeout in milliseconds |
Copy `.env.example` to `.env` and fill in your values:
```bash
cp .env.example .env
```
---
## Adding to MCP Clients
### VS Code (GitHub Copilot)
Create or edit `.vscode/mcp.json` in your workspace:
```json
{
"servers": {
"pyroscope": {
"type": "stdio",
"command": "node",
"args": ["${workspaceFolder}/dist/index.js"],
"env": {
"PYROSCOPE_BASE_URL": "http://localhost:4040"
}
}
}
}
```
Then open the **MCP: List Servers** command in VS Code (`Cmd+Shift+P`) and start the server. Copilot Chat will automatically discover the tools.
For a global (user-level) config instead of per-workspace, add the same block to your VS Code `settings.json` under `"mcp"`:
```json
{
"mcp": {
"servers": {
"pyroscope": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/pyroscope-mcp/dist/index.js"],
"env": {
"PYROSCOPE_BASE_URL": "http://localhost:4040"
}
}
}
}
}
```
---
### Claude Desktop
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"pyroscope": {
"command": "node",
"args": ["/absolute/path/to/pyroscope-mcp/dist/index.js"],
"env": {
"PYROSCOPE_BASE_URL": "http://localhost:4040",
"PYROSCOPE_AUTH_TOKEN": ""
}
}
}
}
```
Restart Claude Desktop. A hammer icon will appear in the chat input when the server is active.
On **Windows**, wrap the command:
```json
{
"mcpServers": {
"pyroscope": {
"command": "cmd",
"args": ["/c", "node", "C:\\path\\to\\pyroscope-mcp\\dist\\index.js"],
"env": {
"PYROSCOPE_BASE_URL": "http://localhost:4040"
}
}
}
}
```
---
### Cursor
Open **Cursor Settings → MCP** and add a new server entry, or edit `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"pyroscope": {
"command": "node",
"args": ["/absolute/path/to/pyroscope-mcp/dist/index.js"],
"env": {
"PYROSCOPE_BASE_URL": "http://localhost:4040"
}
}
}
}
```
Reload Cursor. The tools appear automatically in the Composer agent context.
---
### Zed
Add to your Zed `settings.json` (open via **Zed → Settings**):
```json
{
"context_servers": {
"pyroscope": {
"command": {
"path": "node",
"args": ["/absolute/path/to/pyroscope-mcp/dist/index.js"],
"env": {
"PYROSCOPE_BASE_URL": "http://localhost:4040"
}
}
}
}
}
```
---
### Any MCP-compatible client (generic stdio config)
```json
{
"mcpServers": {
"pyroscope": {
"command": "node",
"args": ["/absolute/path/to/pyroscope-mcp/dist/index.js"],
"env": {
"PYROSCOPE_BASE_URL": "http://localhost:4040",
"PYROSCOPE_AUTH_TOKEN": "your-bearer-token-if-needed",
"PYROSCOPE_TENANT_ID": "your-org-id-if-needed"
}
}
}
}
```
---
## Example prompts once connected
- *"List all services sending profiles in the last hour."*
- *"Show the hottest CPU functions for `media-agent` in the last 30 minutes."*
- *"What is the memory allocation hotspot in `api-gateway`?"*
- *"Compare CPU usage between `worker-service` and `data-pipeline`."*
- *"What profile types are available for `checkout-api`?"*
---
## Notes
- For multi-tenant Pyroscope, set `PYROSCOPE_TENANT_ID` or pass `tenantId` per tool call.
- `pyroscope_connect_query` gives raw access to advanced endpoints:
- `/querier.v1.QuerierService/SelectMergeStacktraces`
- `/querier.v1.QuerierService/SelectSeries`
- `/querier.v1.QuerierService/Diff`
- For Grafana Cloud Pyroscope, set `PYROSCOPE_BASE_URL` to your stack URL and `PYROSCOPE_AUTH_TOKEN` to a service account token.
---
## Query smoke test
1. Start Pyroscope locally:
```bash
docker run -d --name pyroscope -p 4040:4040 grafana/pyroscope:latest
```
2. Query label names from the last hour:
```bash
NOW_MS=$(($(date +%s)*1000))
START_MS=$((NOW_MS-3600000))
curl -sS -H 'Content-Type: application/json' \
-d "{\"start\":$START_MS,\"end\":$NOW_MS}" \
http://localhost:4040/querier.v1.QuerierService/LabelNames
```
3. Query service names from the last hour:
```bash
NOW_MS=$(($(date +%s)*1000))
START_MS=$((NOW_MS-3600000))
curl -sS -H 'Content-Type: application/json' \
-d "{\"name\":\"service_name\",\"start\":$START_MS,\"end\":$NOW_MS}" \
http://localhost:4040/querier.v1.QuerierService/LabelValues
```
