perfetto-mcp-rs

An MCP server for analyzing Perfetto traces with LLMs. Point Claude Code (or any MCP client) at a Perfetto trace file (.pftrace / .perfetto-trace / .bin / etc. — content-sniffed) 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

One-line install (recommended for all platforms) — downloads the prebuilt binary, drops it into ~/.local/bin (or %USERPROFILE%\.local\bin on Windows), adds it to your user PATH if needed, and — if Claude Code and/or Codex are installed — registers the MCP server automatically. Restart Claude Code or start a new Codex session to pick it up. If Qoder is detected, the installer prints a paste-ready JSON snippet (Qoder has no programmatic MCP-registration API yet — open Qoder Settings → MCP → + Add and paste).

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

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

Windows (PowerShell):

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

Alternatives — if you'd rather install through a package manager:

# macOS / Linux via Homebrew
brew tap tooluse-labs/tap
brew install perfetto-mcp-rs
# brew prints caveats; run the printed line to register with Claude Code / Codex:
perfetto-mcp-rs install --binary-path "$(brew --prefix)/bin/perfetto-mcp-rs"

# Rust developers via cargo
cargo install --locked perfetto-mcp-rs
perfetto-mcp-rs install --binary-path "$(which perfetto-mcp-rs)"

Claude scope: registration defaults to --scope user (available from any directory). For a project-local install, set SCOPE=local (or project) and run the script from that project's directory:

SCOPE=local bash -c 'curl -fsSL https://raw.githubusercontent.com/tooluse-labs/perfetto-mcp-rs/main/install.sh | sh'

PowerShell equivalent: $env:SCOPE = 'local'; irm ... | iex. Codex has no scope concept and ignores this variable.

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. Release assets are named perfetto-mcp-rs-<platform> (e.g. perfetto-mcp-rs-linux-amd64); rename or address the downloaded file explicitly when invoking install, and on Unix mark it executable first (chmod +x) — the subcommand refuses non-executable paths to avoid writing a broken MCP entry. Example:

# Linux amd64 example — adjust the asset name for your platform.
curl -fsSL -o perfetto-mcp-rs \
  https://github.com/tooluse-labs/perfetto-mcp-rs/releases/latest/download/perfetto-mcp-rs-linux-amd64
chmod +x perfetto-mcp-rs
./perfetto-mcp-rs install --scope user --binary-path "$PWD/perfetto-mcp-rs"

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 flag:

curl -fsSL https://raw.githubusercontent.com/tooluse-labs/perfetto-mcp-rs/main/install.sh | sh -s -- --version v0.7.0

The VERSION env var also works, but must come immediately before sh (POSIX VAR=value cmd only scopes to the next command — VERSION=v0.7.0 curl ... | sh puts VERSION on curl, not on the piped sh):

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

PowerShell — set $env:VERSION in the same line, since iex runs in the current session:

$env:VERSION = 'v0.7.0'; irm https://raw.githubusercontent.com/tooluse-labs/perfetto-mcp-rs/main/install.ps1 | iex

No auto-update daemon — upgrades are explicit.

Check for updates

perfetto-mcp-rs check-update

Exits 0 if up to date (or ahead of releases — local dev build), 2 if a newer release exists, 1 on network or parse error. Useful for shell-prompt integrations and CI pre-checks.

Uninstall

Symmetric one-liner per platform. Deregisters from Claude Code and Codex, removes the binary, and deletes the cached trace_processor_shell. Idempotent — safe to run if any step was already done by hand.

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

curl -fsSL https://raw.githubusercontent.com/tooluse-labs/perfetto-mcp-rs/main/uninstall.sh | sh

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

irm https://raw.githubusercontent.com/tooluse-labs/perfetto-mcp-rs/main/uninstall.ps1 | iex

Scoped installs (local / project): claude stores local/project entries keyed by project directory, so uninstall must use the same SCOPE AND run from that directory. Omitting this leaves the scoped Claude entry behind while the wrapper still removes the binary and cache:

# Ran `SCOPE=local bash install.sh` in ~/work/foo earlier? Then:
cd ~/work/foo
SCOPE=local bash -c 'curl -fsSL https://raw.githubusercontent.com/tooluse-labs/perfetto-mcp-rs/main/uninstall.sh | sh'

PowerShell equivalent: cd <original-project-dir>; $env:SCOPE = 'local'; irm ... | iex.

$INSTALL_DIR (default ~/.local/bin) is not removed from your PATH:

• Linux / macOS — the installer only prints a PATH hint; if you added it to your shell rc, remove that line manually.

• Windows — the installer writes $INSTALL_DIR into your user PATH (HKCU\Environment); remove it via System Properties → Environment Variables if you want it gone.

Other tools may still depend on this directory, which is why uninstall leaves it in place.

Tools

Resources

Privacy note: MCP tool results are normally visible to the LLM context, and real traces can contain URLs, headers, cookies, and local paths. execute_sql and the dedicated Chrome tools mask sensitive user and credential-like string values by default while keeping the diagnostic structure visible. For raw forensic work, start the server with PERFETTO_MCP_REDACT_STRINGS_DEFAULT=false; load_trace reports the active policy in its summary.

Precision note: dedicated Chrome tools preserve full string cells by default. Use max_string_len only when you explicitly want to trade detail for a smaller response.

Typical flow depends on trace type:

• Chrome traces: load_trace → dedicated chrome_* tools (chrome_scroll_jank_summary, chrome_page_load_summary, chrome_page_load_resource_summary, chrome_page_load_resource_pipeline, chrome_page_load_resource_hotspots, chrome_page_load_script_hotspots, chrome_main_thread_hotspots, chrome_startup_summary, chrome_web_content_interactions) → execute_sql for deeper analysis on the returned rows. For slow FCP/load, check URL-level resource summary first, then use resource pipeline for one slow URL or resource hotspots for slice drilldown, before interpreting main-thread ResourceLoad* slices as full request time. The summary's resource_timing_evidence says whether DNS/TLS/ TTFB/download/cache phase hints exist; keep conclusions at URL lifecycle-span level when phase breakdown is absent. Use script hotspots for post-resource JS and style/layout work, and slice_descendants_breakdown on a long task id when you need its child-slice breakdown.

• Other traces: load_trace → list_tables / list_table_structure for schema discovery → execute_sql for queries. Call list_stdlib_modules or read resource://perfetto-mcp/stdlib-quickref 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-rs -- /absolute/path/to/perfetto-mcp-rs

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

{
  "mcpServers": {
    "perfetto-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/tooluse-labs/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.