py-spy MCP Server
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., "@py-spy MCP Server Generate a flamegraph for the Python process running my Flask app"
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.
py-spy MCP Server
A Model Context Protocol (MCP) server that exposes Python performance testing tools powered by py-spy.
đ 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 shortpy-spy topsession and return a summary.On Windows,
py-spy topcannot 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-spybinary built from the sibling Rust source (src/pyspy/).Optional native/C extension profiling â enable
--nativewhere 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-mcpUsing uv:
uv pip install pyspy-mcp
# or install as a global tool
uv tool install pyspy-mcpThis 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-mcpThe 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 -vThe 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-spyPublishing 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
ptracepermissions (sudoorcap_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 toolsanalyze_profileARead-onlyIdempotent
Analyze an existing py-spy profile and return the hottest frames.
Inputs: profile_path (required), top_n. Returns: result
compare_profilesARead-onlyIdempotent
Compare two speedscope profiles and show percentage changes.
Inputs: profile_a (required), profile_b (required), top_n. Returns: result
dump_stacksARead-onlyIdempotent
Dump the current Python call stacks of a process.
Inputs: pid (required), native, json_output, locals_level, +1 more. Returns: result
list_python_processesARead-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_profileADestructive
Record a sampling profile of a Python process or command.
Inputs: gil, pid, idle, rate, +5 more. Returns: result
top_profileADestructive
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
Scored across 6 tools
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.
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.
With 6 tools, the set covers all essential py-spy operations without being excessive. Each tool earns its place for a focused profiling server.
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
Related MCP Connectors
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Repository knowledge graph MCP server for codebase understanding and debugging.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceThis is a Model Context Protocol (MCP) server implemented in Go, providing a tool to analyze Go pprof performance profiles.50MIT
- AlicenseAqualityCmaintenanceMCP 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.2663 npm10MIT
- AlicenseBqualityDmaintenanceA 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.61MIT
- AlicenseAqualityDmaintenanceMCP server that reads Spark profiler files to give accurate Minecraft server tuning advice, parsing binary protobuf directly and diagnosing TPS, MSPT, GC, heap, and call-tree issues.1428 npm8MIT