A community-driven registry for the Claude Code ecosystem. Not affiliated with Anthropic.
Are you the author? Sign in to claim
Perfetto trace analysis via MCP — PerfettoSQL queries plus dedicated Chrome tools for scroll jank, page loads, and main-
English | 简体中文
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.
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.pftraceand 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.
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
| Tool | Purpose |
|---|---|
load_trace | Open a trace and return a lightweight routing summary (type/profile, duration, platform, process/thread counts, capabilities, redaction policy, recommended next tools) |
execute_sql | Run a PerfettoSQL query (max 5000 returned rows). Prefer the dedicated chrome_* / list_* tools for standard analyses; use this for custom joins or aggregations they don't expose. Output shaping: head/limit, summary, columns_only, include_row_count, max_string_len. Sensitive URL/header/cookie/path values redacted by default |
Exploration
| Tool | Purpose |
|---|---|
list_tables | List tables/views in the loaded trace, optional GLOB filter |
list_table_structure | Show column names and types for a table |
list_processes | List processes (pid, name, start/end timestamps) |
list_threads_in_process | List threads under a process name (up to 2000) |
slice_descendants_breakdown | Summarize child slices under a long slice id without hand-writing recursive CTEs |
list_stdlib_modules | List PerfettoSQL stdlib modules, optional domain / query / limit filters (no trace needed) |
Chrome traces — dedicated tools so the agent doesn't hand-roll SQL. Each flags row/string truncation in its metadata.
| Tool | Purpose |
|---|---|
chrome_scroll_jank_summary | Worst janky frames with cause, sub-cause, delay_since_last_frame |
chrome_page_load_summary | Page loads: URL, raw boundary timestamps, FCP, LCP, DCL, load timings (ms) |
chrome_page_load_resource_summary | Compact URL-level resource/request summary for page-load windows, ranked by max overlap with normalized origin, navigation/renderer relatedness, and attribution-scope evidence |
chrome_page_load_resource_pipeline | One URL's lifecycle/request spans joined with background parse, script evaluation, and style/layout signals, plus an evidence boundary for DNS/TLS/TTFB/cache/download hypotheses |
chrome_page_load_resource_hotspots | URL-bearing resource/request slices on thread, process, and async tracks ranked by page-load/window overlap, with process/thread identity where available |
chrome_page_load_script_hotspots | Renderer main-thread script execution grouped by URL/slice/process within a page-load/window, with style/layout descendant signals |
chrome_main_thread_hotspots | Top main-thread tasks by duration with ts, upid/pid, cpu_pct, and optional page-load/time-window filters |
chrome_startup_summary | Browser startup events and time-to-first-visible-content |
chrome_web_content_interactions | Web content interactions (clicks, taps, INP) ranked by duration |
Resources
| Resource | Purpose |
|---|---|
resource://perfetto-mcp/stdlib-quickref | On-demand PerfettoSQL stdlib quick reference for Chrome, Android, and generic traces |
The right path depends on the trace type:
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.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.
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;
Server settings are read at startup; when both a CLI flag and environment variable exist, the CLI flag wins.
| Setting (flag / env) | Default | Effect |
|---|---|---|
PERFETTO_TP_PATH | — | Path to an existing trace_processor_shell binary; skips auto-download |
--startup-timeout-ms / PERFETTO_STARTUP_TIMEOUT_MS | 20000 | Max time to wait for a spawned trace_processor_shell to become ready (ms) |
--query-timeout-ms / PERFETTO_QUERY_TIMEOUT_MS | 30000 | HTTP timeout for /status and /query requests (ms) |
--max-instances | 3 | Maximum cached trace_processor_shell processes (LRU-evicted) |
--span-timings / PERFETTO_MCP_SPAN_TIMINGS | off | Emit tracing span-close timings for performance hotspot diagnosis (1 / true / yes / on) |
--artifacts-base-url / PERFETTO_ARTIFACTS_BASE_URL | LUCI bucket | Override the trace_processor_shell download source on a cache miss (mirror/proxy; same pinned version) |
PERFETTO_MCP_REDACT_STRINGS_DEFAULT | true | Mask sensitive URL/header/cookie/path strings in tool output; set false for raw forensic work |
PERFETTO_MCP_FULL_TRACE_FINGERPRINT | off | Use full-file SHA-256 for trace cache identity instead of head/middle/tail sampling (1 / true / yes / on) |
RUST_LOG | — | tracing-subscriber filter, e.g. RUST_LOG=debug for verbose logs (written to stderr) |
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 — 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. No auto-update daemon — upgrades are explicit.
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
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:
PATH hint; if you added it
to your shell rc, remove that line manually.$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.
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
Dual-licensed under either of Apache License, Version 2.0 or MIT license at your option. Contributions are accepted under the same terms.
Run Claude Code as an MCP server so any agent can delegate coding tasks to it
Browser automation using accessibility snapshots instead of screenshots
@designcomputerSecure MCP server for MySQL database interaction, queries, and schema management
English-first Korean equity intelligence MCP — DART filings, foreign-holder 5%-rule flows, activist filings, KRX news. F
