perfetto-mcp-rs

English | 简体中文

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

macOS / Linux (Homebrew, recommended):

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 (cargo install):

cargo install --locked perfetto-mcp-rs
perfetto-mcp-rs install --binary-path "$(which perfetto-mcp-rs)"

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

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

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.

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

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/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.