Skip to main content
Glama
walac

perf-mcp

by walac
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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: MCP Filesystem Server

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": "uvx",
      "args": ["--from", "git+https://github.com/walac/perf-mcp", "perf-mcp"],
      "type": "stdio"
    }
  }
}

Other MCP Clients

Run as a stdio MCP server:

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

Configuration

Environment Variable

Default

Description

PERF_BINARY

perf

Path to the perf binary

PERF_TIMEOUT

60

Command timeout in seconds (max 300)

PERF_MAX_OUTPUT_BYTES

2000000

Output truncation limit (bytes)

Set via the env key in .mcp.json:

{
  "mcpServers": {
    "perf-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/walac/perf-mcp", "perf-mcp"],
      "type": "stdio",
      "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

Tool

Command

What it does

perf_evlist

perf evlist

List recorded events (start here)

perf_report

perf report

Overhead histogram by symbol/DSO/thread

perf_script

perf script

Raw per-sample event dump

perf_annotate

perf annotate

Source/assembly with per-line hit counts

perf_diff

perf diff

Compare two profiles side-by-side

perf_c2c_report

perf c2c report

False sharing / cache contention

perf_inject

perf inject

Decode Intel PT, inject build IDs

Scheduler

Tool

Command

perf_sched_latency

Per-task scheduling latency stats

perf_sched_timehist

Timestamped context switch timeline

perf_sched_map

ASCII CPU activity map

perf_sched_script

Raw scheduler event dump

perf_sched_replay

Replay scheduling for simulation

Locks

Tool

Command

perf_lock_report

Lock acquire/contention statistics

perf_lock_contention

Contention analysis with BPF support

perf_lock_info

Lock type information

Kernel Work Items

Tool

Command

perf_kwork_report

IRQ/softirq/workqueue statistics

perf_kwork_latency

Work item latency breakdown

perf_kwork_timehist

Timestamped work item events

perf_kwork_top

Top work items by runtime

Memory, KVM, Utilities

Tool

Command

perf_kmem_stat

Kernel memory allocation stats

perf_mem_report

Memory access data source analysis

perf_kvm_stat_report

KVM VM exit statistics

perf_timechart

Generate scheduling timechart SVG

perf_buildid_list

List binary build IDs

perf_data_convert

Convert perf.data to JSON/CTF

perf_kallsyms

Kernel symbol lookup

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)

Install Server
F
license - not found
A
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

  • Code Search MCP

    LLMTooling
    F
    license
    -
    quality
    D
    maintenance
    Enables LLMs to perform high-performance code search and analysis across multiple languages using symbol indexing, regex text search, and structural AST pattern matching. It also provides tools for technology stack detection and dependency analysis with persistent caching for optimized performance.
    7

  • MCP Filesystem Server

    williamRR
    A
    license
    -
    quality
    D
    maintenance
    Provides LLM-optimized tools for advanced code analysis, repository complexity evaluation, and call graph generation. It enables users to visualize directory structures, detect code patterns, and build semantic context with significant token savings.
    8
    MIT

  • ebpf-mcp-tracer

    blackdragoon26
    F
    license
    -
    quality
    B
    maintenance
    Enables LLMs to safely write and run bpftrace scripts against the Linux kernel for observability, with explicit probe allowlists and execution timeout.
    1

View all related MCP servers

Related MCP Connectors

  • DepScope

    Package intelligence MCP for AI agents — 22 tools, 19 ecosystems, AGPL SDK, free.

  • ai-netcafe

    23 agent tools + a measured per-call model cost dataset. No key needed to start.

  • Intent-Verified Development (IVD)

    33 tools that make AI write, implement, and verify intent against explicit, testable constraints.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/walac/perf-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server