Perfetto

Turn natural language into powerful Perfetto trace analysis. Quickly explain jank, diagnose ANRs, spot CPU hot threads, uncover lock contention, and find memory leaks.

GitHub

showcase

Perfetto MCP

Turn natural language into powerful Perfetto trace analysis

A Model Context Protocol (MCP) server that transforms natural-language prompts into focused Perfetto analyses. Quickly explain jank, diagnose ANRs, spot CPU hot threads, uncover lock contention, and find memory leaks – all without writing SQL.

✨ Features

  • Natural Language → SQL: Ask questions in plain English, get precise Perfetto queries
  • ANR Detection: Automatically identify and analyze Application Not Responding events
  • Performance Analysis: CPU profiling, frame jank detection, memory leak detection
  • Thread Contention: Find synchronization bottlenecks and lock contention
  • Binder Profiling: Analyze IPC performance and slow system interactions

showcase

📋 Prerequisites

  • Python 3.13+ (macOS/Homebrew): 
    brew install [email protected]
  • uv (recommended): 
    brew install uv

🚀 Getting Started

Cursor

Install MCP Server

Or add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "perfetto-mcp": {
      "command": "uvx",
      "args": ["perfetto-mcp"]
    }
  }
}
Claude Code

Run this command. See Claude Code MCP docs for more info.

# Add to user scope
claude mcp add perfetto-mcp --scope user -- uvx perfetto-mcp

Or edit ~/claude.json (macOS) or %APPDATA%\Claude\claude.json (Windows):

{
  "mcpServers": {
    "perfetto-mcp": {
      "command": "uvx",
      "args": ["perfetto-mcp"]
    }
  }
}
VS Code

Install in VS Code

or add to .vscode/mcp.json (project) or run "MCP: Add Server" command:

{
  "mcpServers": {
    "perfetto-mcp": {
      "command": "uvx",
      "args": ["perfetto-mcp"]
    }
  }
}

Enable in GitHub Copilot Chat's Agent mode.

Codex

Edit ~/.codex/config.toml:

[mcp_servers.perfetto-mcp]
command = "uvx"
args = ["perfetto-mcp"]

Local Install (development server)

cd perfetto-mcp-server
uv sync
uv run mcp dev src/perfetto_mcp/dev.py
Local MCP 
{
  "mcpServers": {
    "perfetto-mcp-local": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/git/repo/perfetto-mcp",
        "run",
        "-m",
        "perfetto_mcp"
      ],
      "env": { "PYTHONPATH": "src" }
    }
  }
}
Using pip 
pip3 install perfetto-mcp
python3 -m perfetto_mcp

📖 How to Use

Example starting prompt:

In the perfetto trace, I see that the FragmentManager is taking 438ms to execute. Can you figure out why it's taking so long?

Required Parameters

Every tool needs these two inputs:

ParameterDescriptionExample
trace_pathAbsolute path to your Perfetto trace/path/to/trace.perfetto-trace
process_nameTarget process/app namecom.example.app

In Your Prompts

Be explicit about the trace and process, prefix your prompt with:

"Use perfetto trace /absolute/path/to/trace.perfetto-trace for process com.example.app"

Optional Filters

Many tools support additional filtering (but let your LLM handle that):

  • time_range: {start_ms: 10000, end_ms: 25000}
  • Tool-specific thresholds: min_block_ms, jank_threshold_ms, limit

🛠️ Available Tools

🔎 Exploration & Discovery

ToolPurposeExample Prompt
find_slicesSurvey slice names and locate hot paths"Find slice names containing 'Choreographer' and show top examples"
execute_sql_queryRun custom PerfettoSQL for advanced analysis"Run custom SQL to correlate threads and frames in the first 30s"

🚨 ANR Analysis

Note: Helpful if the recorded trace contains ANR

ToolPurposeExample Prompt
detect_anrsFind ANR events with severity classification"Detect ANRs in the first 10s and summarize severity"
anr_root_cause_analyzerDeep-dive ANR causes with ranked likelihood"Analyze ANR root cause around 20,000 ms and rank likely causes"

🎯 Performance Profiling

ToolPurposeExample Prompt
cpu_utilization_profilerThread-level CPU usage and scheduling"Profile CPU usage by thread and flag the hottest threads"
main_thread_hotspot_slicesFind longest-running main thread operations"List main-thread hotspots >50 ms during 10s–25s"

📱 UI Performance

ToolPurposeExample Prompt
detect_jank_framesIdentify frames missing deadlines"Find janky frames above 16.67 ms and list the worst 20"
frame_performance_summaryOverall frame health metrics"Summarize frame performance and report jank rate and P99 CPU time"

🔒 Concurrency & IPC

ToolPurposeExample Prompt
thread_contention_analyzerFind synchronization bottlenecks"Find lock contention between 15s–30s and show worst waits"
binder_transaction_profilerAnalyze Binder IPC performance"Profile slow Binder transactions and group by server process"

💾 Memory Analysis

ToolPurposeExample Prompt
memory_leak_detectorFind sustained memory growth patterns"Detect memory-leak signals over the last 60s"
heap_dominator_tree_analyzerIdentify memory-hogging classes"Analyze heap dominator classes and list top offenders"

Output Format

All tools return structured JSON with:

  • Summary: High-level findings
  • Details: Tool-specific results
  • Metadata: Execution context and any fallbacks used

📚 Resources

📄 License

Apache 2.0 License. See LICENSE for details.

GitHub • Issues • Documentation

関連サーバー