Skip to main content
Glama
py-spy MCP Server

py-spy MCP Server

by LBurny

py-spy MCP Server

A Model Context Protocol (MCP) server that exposes Python performance testing tools powered by py-spy.

License: MIT Python 3.10+ MCP Compatible tests passing

🌐 English | įŽ€äŊ“中文

Profile Python in context. Sample live processes, generate flamegraphs, dump stacks, and compare runs — all through MCP.

Features

  • Profile by PID or command — sample a running Python process or launch a new one directly.

  • record_profile — generate profiles in multiple formats:

    • speedscope (interactive JSON)

    • flamegraph (self-contained SVG)

    • raw (stack-count text)

    • chrometrace (Chrome DevTools timeline JSON)

  • dump_stacks — capture the current Python call stacks of a process as JSON or human-readable text.

  • list_python_processes — list running Python processes on the machine to pick a target.

  • analyze_profile — parse an existing profile and return the hottest frames.

  • compare_profiles — compare two speedscope profiles and show percentage changes.

  • top_profile — run a short py-spy top session and return a summary.

    • On Windows, py-spy top cannot be captured through a pipe, so this tool falls back to a short raw recording and returns the hottest frames.

  • Low-overhead sampling — powered by py-spy; reads process memory without modifying or running inside the target process.

  • Cross-platform — works on Linux, macOS, and Windows (subject to OS permissions).

  • Local-source friendly — during development the server automatically prefers a py-spy binary built from the sibling Rust source (src/pyspy/).

  • Optional native/C extension profiling — enable --native where the platform supports it.

  • GIL and idle filtering — focus on active threads or GIL-holding threads.

Related MCP server: javaperf

Installation (from PyPI)

Using pip:

pip install pyspy-mcp

Using uv:

uv pip install pyspy-mcp
# or install as a global tool
uv tool install pyspy-mcp

This will automatically install the compatible py-spy binary wheel for your platform.

Running with Claude Desktop / Claude Code

Add the server as a Local command connector:

{
  "mcpServers": {
    "pyspy": {
      "command": "pyspy-mcp"
    }
  }
}

Or run directly:

pyspy-mcp

The server speaks MCP over stdio.

Development (from source)

If you want to use the local py-spy Rust source instead of the PyPI package:

# Build py-spy from the local Rust source
cargo build --release

# The binary will be at:
#   target/release/py-spy        (Linux / macOS)
#   target/release/py-spy.exe    (Windows)

# Install the Python MCP package in editable mode
pip install -e ".[dev]"

# Or using uv
uv pip install -e ".[dev]"

# Run tests
python -m pytest tests/pyspy_mcp -v

The server will automatically prefer a locally built binary at target/release/py-spy[.exe] over the py-spy installed from PyPI. You can also force a specific binary by setting the environment variable:

export PYSPY_MCP_BINARY=/path/to/py-spy

Publishing to PyPI

python -m build
python -m twine upload dist/*

The published wheel is a pure-Python py3-none-any package and depends on the upstream py-spy PyPI package. If you modify the Rust source and want to ship those changes, you will need to build platform-specific wheels (or bundle the rebuilt py-spy binary as package data).

Permissions

  • On Linux, profiling an existing PID usually requires ptrace permissions (sudo or cap_sys_ptrace).

  • On macOS, profiling often requires root due to System Integrity Protection (SIP).

  • On Windows, running as Administrator may be needed for some processes.

Configuration

Set PYSPY_MCP_BINARY to override the bundled/development py-spy binary location.

Available Tools

6 tools
analyze_profileA
Read-onlyIdempotent

Analyze an existing py-spy profile and return the hottest frames.

Inputs: profile_path (required), top_n. Returns: result

compare_profilesA
Read-onlyIdempotent

Compare two speedscope profiles and show percentage changes.

Inputs: profile_a (required), profile_b (required), top_n. Returns: result

dump_stacksA
Read-onlyIdempotent

Dump the current Python call stacks of a process.

Inputs: pid (required), native, json_output, locals_level, +1 more. Returns: result

list_python_processesA
Read-onlyIdempotent

List running Python processes on this machine.

Returns: A table of PID, memory usage, and command line.

Inputs: no named parameters. Returns: result

record_profileA
Destructive

Record a sampling profile of a Python process or command.

Inputs: gil, pid, idle, rate, +5 more. Returns: result

top_profileA
Destructive

Run a live py-spy top view for a few seconds and return the summary.

On Windows, py-spy top cannot be captured through a pipe, so this tool falls back to a short record --format raw sample and returns the hottest frames instead of raw top output.

Inputs: gil, pid, idle, rate, +4 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogâ€Ļ

    TDQS

    A4/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: listing processes, recording, analyzing, comparing, dumping stacks, and live top view. No two tools overlap, making selection unambiguous for an agent.

    Naming Consistency4/5

    Most tools follow a verb_noun pattern (e.g., list_python_processes, record_profile). The tool 'top_profile' deviates slightly by using 'top' as a verb, but it is still interpretable. Overall consistent.

    Tool Count5/5

    With 6 tools, the set covers all essential py-spy operations without being excessive. Each tool earns its place for a focused profiling server.

    Completeness5/5

    The tools cover the full lifecycle of profiling: process discovery, recording, analysis, comparison, stack inspection, and live monitoring. No major gaps are apparent for the intended use case.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      MCP server for profiling Java applications via JDK utilities (jcmd, jfr, jps). Enables AI assistants to diagnose performance, analyze threads, and inspect JFR recordings without manual CLI usage.
      26
      63 npm
      10
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      A read-only MCP server for Grafana Pyroscope that lets AI assistants query continuous profiling data, including flamegraphs, hotspot functions, memory allocations, and label discovery, directly from any MCP-compatible client.
      6
      1
      MIT