perfetto-mcp-rs

English | 简体中文

An MCP server for analyzing
Perfetto traces with LLMs. Point Claude Code (or any
MCP client) at a .perfetto-trace / .pftrace file and query it with
PerfettoSQL.

Backed by trace_processor_shell — downloaded automatically on first run, no
manual Perfetto install required.

Works best with agentic MCP clients (Claude Code, Claude Desktop, Cursor)
that can chain multi-turn tool calls. Non-agentic clients will see the same
tools but won't be able to follow the error-message nudges that steer the
LLM through the typical load_trace → list_tables → table_structure →
execute_sql flow.

Quick install

Linux / macOS / Windows (Git Bash, MSYS2, Cygwin):

curl -fsSL https://raw.githubusercontent.com/0xZOne/perfetto-mcp-rs/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/0xZOne/perfetto-mcp-rs/main/install.ps1 | iex

Both installers drop the prebuilt binary into ~/.local/bin (or
%USERPROFILE%\.local\bin on Windows), add it to your user PATH if needed,
and — if Claude Code is installed — register it as a user-scope MCP server.
Restart Claude Code to pick it up.

Supported platforms: linux amd64/arm64, macOS amd64/arm64, Windows amd64.
If you'd rather not run a script, grab the binary directly from the
releases page.

Uninstall

One-liner per platform. Unregisters the MCP server from Claude Code,
removes the binary, and deletes the cached trace_processor_shell.

Linux:

claude mcp remove perfetto-mcp-rs --scope user 2>/dev/null; rm -f ~/.local/bin/perfetto-mcp-rs; rm -rf ~/.local/share/perfetto-mcp-rs

macOS:

claude mcp remove perfetto-mcp-rs --scope user 2>/dev/null; rm -f ~/.local/bin/perfetto-mcp-rs; rm -rf "$HOME/Library/Application Support/perfetto-mcp-rs"

Windows (PowerShell) — close Claude Code first so the .exe isn't locked:

if (Get-Command claude -ErrorAction SilentlyContinue) { claude mcp remove perfetto-mcp-rs --scope user 2>$null }; Remove-Item -Force "$HOME\.local\bin\perfetto-mcp-rs.exe*" -ErrorAction SilentlyContinue; Remove-Item -Recurse -Force "$env:LOCALAPPDATA\perfetto-mcp-rs" -ErrorAction SilentlyContinue

Tools

Typical flow: load_trace → list_tables to discover the schema →
table_structure on interesting tables → execute_sql to query. Chrome and
Android trace analysis is done via INCLUDE PERFETTO MODULE chrome.xyz /
android.xyz — the included modules persist for subsequent queries against
the same trace.

Example

Ask Claude Code something like:

Load ~/traces/scroll_jank.pftrace and tell me the top scroll jank causes.

Claude will call load_trace, then issue a query like:

INCLUDE PERFETTO MODULE chrome.scroll_jank.scroll_jank_v3;
SELECT cause_of_jank, COUNT(*) AS n
FROM chrome_janky_frames
GROUP BY cause_of_jank
ORDER BY n DESC;

Manual MCP client configuration

If the installer's auto-registration doesn't apply to your client, add this
to your MCP server config (e.g. ~/.claude.json or .mcp.json):

{
  "mcpServers": {
    "perfetto-mcp-rs": {
      "command": "/absolute/path/to/perfetto-mcp-rs"
    }
  }
}

Configuration

CLI flags:

Build from source

Requires a Rust toolchain and protoc (Protocol Buffers compiler):

# Ubuntu/Debian
sudo apt install -y protobuf-compiler
# macOS
brew install protobuf
# Windows
choco install protoc

Then:

git clone https://github.com/0xZOne/perfetto-mcp-rs
cd perfetto-mcp-rs
cargo build --release
# Binary at target/release/perfetto-mcp-rs

Development

cargo test          # unit tests
cargo clippy        # lint
cargo fmt           # format

License

Dual-licensed under either of Apache License, Version 2.0 or
MIT license at your option. Contributions are accepted under
the same terms.