Py Spy Server

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

License: MIT

🌐 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.

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.