tooluse-labs/perfetto-mcp-rs

---
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:
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.
Tools
For one trace, other tools act on the most recently loaded trace by default. For
multiple traces, call load_trace with paths, keep the returned trace_id for
each file, and pass the intended id to every trace-bound tool call.
MCP tool annotations are client-facing intent and safety hints, not server-side
authorization or execution boundaries.
**Essential**
| Tool | Purpose |
|---|---|
| load_trace | Open one trace with path, or several with paths; returns an opaque trace_id and lightweight routing summary for each file (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 |