<p align="center"> <img src="assets/brand/logo-wordmark.svg" width="820" alt="perfetto-mcp-rs logo"> </p>

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

Tool	Purpose
load_trace	Open a .perfetto-trace / .pftrace file (must be called first)
list_tables	List tables/views in the loaded trace, optional GLOB filter
list_table_structure	Show column names and types for a table
execute_sql	Run a PerfettoSQL query, returns JSON rows (max 5000)
list_processes	List processes in the trace (pid, name, start/end timestamps)
list_threads_in_process	List threads under a process name (up to 2000)
chrome_scroll_jank_summary	Worst janky frames with cause, sub-cause, delay_since_last_frame (Chrome trace)
chrome_page_load_summary	Page loads: URL, FCP, LCP, DCL, load timings in ms (Chrome trace)
chrome_main_thread_hotspots	Top main-thread tasks by duration with cpu_pct, uses is_main_thread (Chrome trace)
chrome_startup_summary	Browser startup events and time-to-first-visible-content (Chrome trace)
chrome_web_content_interactions	Web content interactions (clicks, taps, INP) ranked by duration (Chrome trace)
list_stdlib_modules	List available PerfettoSQL stdlib modules with usage examples (no trace needed)

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

Variable	Effect
PERFETTO_TP_PATH	Path to an existing trace_processor_shell binary; skips auto-download
PERFETTO_STARTUP_TIMEOUT_MS	Overrides the trace_processor_shell startup timeout in milliseconds
PERFETTO_QUERY_TIMEOUT_MS	Overrides the HTTP status/query timeout in milliseconds
RUST_LOG	tracing-subscriber filter, e.g. RUST_LOG=debug for verbose logs (written to stderr)

CLI flags:

Flag	Default	Description
--max-instances	3	Maximum cached trace_processor_shell processes (LRU-evicted)
--startup-timeout-ms	5000	Max time to wait for a spawned trace_processor_shell to become ready
--query-timeout-ms	30000	HTTP timeout for /status and /query requests

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.