English | 简体中文

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.

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

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.

Analyzing multiple traces

Load comparison targets together with load_trace(paths=[...]). The response returns one stable trace_id per file. Run the same trace-bound tool for each id (concurrently when the MCP client supports parallel tool calls), then compare the returned evidence. Calls without trace_id remain backward compatible and use the most recently loaded trace. If a loaded file changes on disk, its old id is rejected with an explicit instruction to reload it.

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.