perf-mcp

MCP server for Linux perf. Gives LLMs structured access to perf report, perf script, perf annotate, and 23 other perf analysis commands through typed tool parameters.

Operates on existing perf.data files only -- no recording, no system modification.

Requirements

• Linux with perf installed (perf --version)

• Python 3.12+

• uv

Related MCP server: systerd-lite

Quick Start

git clone <repo-url> ~/work/perf-mcp
cd ~/work/perf-mcp
uv sync

Claude Code

Add to .mcp.json (project or global):

{
  "mcpServers": {
    "perf-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "<path-to-perf-mcp>", "perf-mcp"]
    }
  }
}

Replace <path-to-perf-mcp> with the absolute path to your clone.

Other MCP Clients

Run as a stdio MCP server:

cd ~/work/perf-mcp
uv run perf-mcp

Configuration

Set via the env key in .mcp.json:

{
  "mcpServers": {
    "perf-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "<path>", "perf-mcp"],
      "env": {
        "PERF_TIMEOUT": "120"
      }
    }
  }
}

Tools

26 tools across 7 categories. Each wraps a perf subcommand with every CLI option exposed as a typed parameter.

Core Analysis

Scheduler

Locks

Kernel Work Items

Memory, KVM, Utilities

Typical Workflow

1. Record a profile (outside this tool): perf record -g -a -- sleep 10

2. Ask the LLM to analyze it:

   • "What events are in ./perf.data?" -- calls perf_evlist

   • "Show the top CPU consumers" -- calls perf_report

   • "Annotate the hottest function" -- calls perf_annotate

   • "Show the raw samples for malloc" -- calls perf_script with symbols='malloc'

   • "Compare before and after" -- calls perf_diff

Safety

• Read-only -- no recording or data modification commands

• Path validation -- input/output paths validated, /proc /sys /dev /etc blocked

• No code execution -- --script, --dlfilter, --objdump, --addr2line options excluded

• Timeout enforcement -- processes killed after the configured limit

• Output truncation -- large outputs capped with a clear marker

• No shell -- all commands use subprocess.exec (no shell injection)