perfetto-mcp-rs

An MCP server that lets LLMs analyze Perfetto traces. Point Claude Code (or any MCP client) at a trace file (.pftrace / .perfetto-trace / .bin / … — content-sniffed) and ask in plain language. The server runs PerfettoSQL under the hood, backed by trace_processor_shell — downloaded automatically on first run, no manual Perfetto install required.

Dedicated tools ship curated SQL; for custom analysis the agent writes PerfettoSQL — steered toward the right stdlib modules.

Quick start

You drive perfetto-mcp-rs through an MCP client (Claude Code, Claude Desktop, Codex, Cursor, …) — install one first if you don't have it.

1. Install — downloads the prebuilt binary and, if Claude Code and/or Codex are present, registers the MCP server automatically:

# 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

Restart Claude Code (or start a new Codex session) to pick it up. Homebrew, Cargo, project scope, direct-binary download, and manual registration are under Install options.

2. Ask in plain language:

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

Swap in any Perfetto trace you have — captured from the Perfetto UI, chrome://tracing, or record_android_trace.

The agent calls load_trace, sees it's a Chrome trace, and reaches for the dedicated chrome_scroll_jank_summary tool — no SQL to hand-write. When a question falls outside the dedicated tools, it drops down to execute_sql with raw PerfettoSQL on the same trace.

Works best with agentic clients (Claude Code, Codex, Claude Desktop, Cursor) that chain multi-turn tool calls and follow the server's error-message nudges. Non-agentic clients see the same tools and error nudges, but won't chain the guided flow automatically.

Related MCP server: mcp-server-logs-sieve

Tools

Switching traces means re-calling load_trace — there is no path argument on the other tools; they all act on the most recently loaded trace.

MCP tool annotations are client-facing intent and safety hints, not server-side authorization or execution boundaries.

Essential

Exploration

Chrome traces — dedicated tools so the agent doesn't hand-roll SQL. Each flags row/string truncation in its metadata.

Resources

Analyzing a trace

The right path depends on the trace type:

• Chrome traces — load_trace → dedicated chrome_* tools → execute_sql for deeper cuts on the returned rows. For slow FCP/load, check chrome_page_load_resource_summary first, then chrome_page_load_resource_pipeline for one slow URL or chrome_page_load_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 chrome_page_load_script_hotspots for post-resource JS and style/layout work, and slice_descendants_breakdown on a long task id for its child-slice breakdown.

• Other traces (Android, generic) — load_trace → list_stdlib_modules (or read resource://perfetto-mcp/stdlib-quickref) to check for a ready-made module first (Android, generic modules like slices.with_context), then run it via execute_sql + INCLUDE PERFETTO MODULE. No module fits? Fall back to list_tables / list_table_structure for schema discovery, then execute_sql.

Privacy — tool results enter the LLM context, and real traces can hold URLs, headers, cookies, and local paths. execute_sql and the dedicated Chrome tools mask sensitive user and credential-like 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 — 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.

Under the hood: dedicated tool vs. raw SQL

The scroll-jank question above resolves to a single chrome_scroll_jank_summary call — no SQL to write. When you need a cut the dedicated tools don't expose, the agent drops to execute_sql with PerfettoSQL; the same breakdown by hand:

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;

Configuration

Server settings are read at startup; when both a CLI flag and environment variable exist, the CLI flag wins.

Install options

Package managers — if you'd rather not run the install script:

# 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)"

If Qoder is detected during a script install, the installer prints a paste-ready JSON snippet (Qoder has no programmatic MCP-registration API yet — open Qoder Settings → MCP → + Add and paste).

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.

Direct binary — supported platforms: linux amd64/arm64, macOS amd64/arm64, Windows amd64. Grab the binary 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"

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"
    }
  }
}

Upgrade & uninstall

Upgrade — run the update subcommand:

perfetto-mcp-rs update

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. No auto-update daemon — upgrades are explicit.

Pin to a specific version with the --version flag:

perfetto-mcp-rs update --version v0.7.0

For Claude local/project registrations, re-run from the original project directory and pass the same scope:

perfetto-mcp-rs update --scope local

The raw installer one-liners still work if you prefer to drive upgrades manually or need installer-specific environment overrides.

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

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. If it reports a newer release, run perfetto-mcp-rs update.

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.

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.