pyroscope-mcp
Provides tools to query continuous profiling data from Grafana Pyroscope, including flamegraphs, hotspot functions, memory allocations, and label discovery.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pyroscope-mcp Show the hottest CPU functions for api-gateway in the last 30 minutes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
pyroscope-mcp
A read-only Model Context Protocol (MCP) server for Grafana 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 |
| Flamegraph + timeline data from |
| List all label names in a time range |
| List values for a given label (e.g. |
| List available profile types (cpu, memory, goroutines…) |
| Fetch matching label sets for a selector |
| Raw access to any |
Related MCP server: Grafana MCP Server
Prerequisites
Node.js 20+
A running Pyroscope instance (local, self-hosted, or Grafana Cloud)
Setup
git clone https://github.com/your-org/pyroscope-mcp
cd pyroscope-mcp
npm install
npm run buildConfiguration
All settings are provided via environment variables:
Variable | Default | Description |
|
| Pyroscope server URL |
| — | Bearer token (Grafana Cloud or Azure AD) |
| — | Multi-tenant org ID ( |
|
| Request timeout in milliseconds |
Copy .env.example to .env and fill in your values:
cp .env.example .envAdding to MCP Clients
VS Code (GitHub Copilot)
Create or edit .vscode/mcp.json in your workspace:
{
"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":
{
"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):
{
"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:
{
"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:
{
"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):
{
"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)
{
"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-agentin the last 30 minutes.""What is the memory allocation hotspot in
api-gateway?""Compare CPU usage between
worker-serviceanddata-pipeline.""What profile types are available for
checkout-api?"
Notes
For multi-tenant Pyroscope, set
PYROSCOPE_TENANT_IDor passtenantIdper tool call.pyroscope_connect_querygives raw access to advanced endpoints:/querier.v1.QuerierService/SelectMergeStacktraces/querier.v1.QuerierService/SelectSeries/querier.v1.QuerierService/Diff
For Grafana Cloud Pyroscope, set
PYROSCOPE_BASE_URLto your stack URL andPYROSCOPE_AUTH_TOKENto a service account token.
Query smoke test
Start Pyroscope locally:
docker run -d --name pyroscope -p 4040:4040 grafana/pyroscope:latestQuery label names from the last hour:
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/LabelNamesQuery service names from the last hour:
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/LabelValuesAvailable Tools
6 toolspyroscope_connect_queryC
Execute any Pyroscope Connect query endpoint with a raw JSON request body.
Inputs: body (required), endpoint (required), baseUrl, tenantId.
pyroscope_label_namesC
List available label names via Connect API.
Inputs: end, start, baseUrl, matchers, +1 more.
pyroscope_label_valuesC
List label values for a given label name via Connect API.
Inputs: name (required), end, start, baseUrl, +2 more.
pyroscope_profile_typesC
List available profile types via Connect API.
Inputs: end, start, baseUrl, tenantId.
pyroscope_render_profileB
Query the legacy /pyroscope/render endpoint for flamegraph and timeline data.
Inputs: query (required), from, until, format, +4 more.
pyroscope_seriesC
Return profile series for given matchers via Connect API.
Inputs: end, start, baseUrl, matchers, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct operation: executing raw queries, listing labels, label values, profile types, rendering profiles, and retrieving series. No two tools have overlapping functionality.
All tool names follow a consistent 'pyroscope_{verb_or_noun}' pattern in snake_case, making the set predictable and easy to navigate.
Six tools is a reasonable count for a profiling API client, covering essential operations without being too sparse or bloated. Slight under-coverage is possible but acceptable.
The set covers key Pyroscope API operations: querying, metadata (labels, profile types), and data retrieval (render, series). Minor gaps like specific profile operations or CRUD might exist but are not critical for typical usage.
Maintenance
Related MCP Connectors
The Polar Signals MCP server enables AI assistants to connect directly with performance profiling data, allowing users to analyze application performance through natural language queries. Key capabilities include querying CPU performance and memory usage, exploring profiling metadata like profile types and labels, and providing AI-driven code optimization suggestions directly within development environments like Claude Code or Cursor.
The Grafbase MCP server sits in front of a GraphQL API and exposes an MCP protocol-compliant interface that allows AI agents and LLMs to explore and query GraphQL APIs using natural language. It provides tools to search schemas, introspect types and fields, and execute GraphQL queries while minimizing context bloat by returning only relevant schema subsets, with built-in support for authentication, authorization, and configurable access control.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
Query application logs, traces, and metrics from your AI coding assistant via Foam's MCP server.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI assistants to interact with Signoz observability platform, providing tools to query dashboards, metrics, traces, logs, and APM data with time range support.14MIT
- AlicenseAqualityDmaintenanceA server that enables AI assistants to access and query Grafana dashboards, metrics, logs, and configurations through an MCP protocol interface.106MIT
- AlicenseAqualityDmaintenanceMCP server that enables AI assistants to query Grafana/Loki logs and Thanos/Prometheus metrics directly from MCP-compatible clients like Cursor or Claude Desktop.8MIT
- AlicenseNot gradedqualityDmaintenanceA read-only MCP server that enables agents to query and analyze Langfuse observability data, including traces, sessions, observations, scores, and metrics.MIT