Perfetto MCP

🚀 Perfetto MCP

Transform natural language into powerful Perfetto trace analysis.

Perfetto MCP is a Model Context Protocol (MCP) server that translates natural - language prompts into targeted Perfetto analyses. It enables users to quickly explain jank, diagnose ANRs, spot CPU hot threads, uncover lock contention, and find memory leaks without writing SQL.

✨ Features

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

📋 Prerequisites

• Python 3.13+ (macOS/Homebrew):

  brew install python@3.13
  

• uv (recommended):

  brew install uv
  

🚀 Quick Start

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

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

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

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

[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

{
  "mcpServers": {
    "perfetto-mcp-local": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/git/repo/perfetto-mcp",
        "run",
        "-m",
        "perfetto_mcp"
      ],
      "env": { "PYTHONPATH": "src" }
    }
  }
}

pip3 install perfetto-mcp
python3 -m perfetto_mcp

💻 Usage Examples

Basic Usage

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:

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 (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

🚨 ANR Analysis

Note: Helpful if the recorded trace contains ANR

🎯 Performance Profiling

📱 UI Performance

🔒 Concurrency & IPC

💾 Memory Analysis

Output Format

All tools return structured JSON with:

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

📚 Documentation

• Trace Processor Python API - Perfetto's Python interface
• Perfetto SQL Syntax - SQL reference for custom queries

📄 License

This project is under the Apache 2.0 License. See LICENSE for details.

GitHub • Issues • Documentation