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, Codex, 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 → list_table_structure → execute_sql flow.

Navigate agents toward the right PerfettoSQL stdlib modules — the analysis SQL is always the agent's own.

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 and/or Codex are installed — register it automatically. Restart Claude Code or start a new Codex session 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.

Upgrade

Re-run the same install command — it pulls the latest release, safely overwrites the existing binary (with Windows file-lock retry), and re-registers the MCP server with Claude Code / Codex idempotently.

Pin to a specific version with the VERSION env var:

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

No auto-update daemon — upgrades are explicit.

Uninstall

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

Linux:

if command -v claude >/dev/null 2>&1; then claude mcp remove perfetto-mcp-rs --scope user 2>/dev/null; fi; if command -v codex >/dev/null 2>&1; then codex mcp remove perfetto-mcp-rs 2>/dev/null; fi; rm -f ~/.local/bin/perfetto-mcp-rs; rm -rf ~/.local/share/perfetto-mcp-rs

macOS:

if command -v claude >/dev/null 2>&1; then claude mcp remove perfetto-mcp-rs --scope user 2>/dev/null; fi; if command -v codex >/dev/null 2>&1; then codex mcp remove perfetto-mcp-rs 2>/dev/null; fi; rm -f ~/.local/bin/perfetto-mcp-rs; rm -rf "$HOME/Library/Application Support/perfetto-mcp-rs"

Windows (PowerShell) — close Claude Code, Codex, or anything else using the .exe first:

if (Get-Command claude -ErrorAction SilentlyContinue) { claude mcp remove perfetto-mcp-rs --scope user 2>$null }; if (Get-Command codex -ErrorAction SilentlyContinue) { codex mcp remove perfetto-mcp-rs 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 depends on trace type:

• Chrome traces: load_trace → dedicated chrome_* tools (chrome_scroll_jank_summary, chrome_page_load_summary, chrome_main_thread_hotspots, chrome_startup_summary, chrome_web_content_interactions) → execute_sql for deeper analysis on the returned rows.
• Other traces: load_trace → list_tables / list_table_structure for schema discovery → execute_sql for queries. Call list_stdlib_modules as an auxiliary when stdlib modules might cover your analysis (Android, generic modules like slices.with_context).

Example

Ask Claude Code or Codex 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:

Codex:

codex mcp add perfetto-mcp-rs -- /absolute/path/to/perfetto-mcp-rs

JSON-based clients (e.g. Claude Code, Claude Desktop, Cursor):

{
  "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.