mcpField
P
Perfetto

Perfetto

Local
github.com/antarikshcDeveloper Tools222Updated 29w ago
Repository

About Perfetto

Perfetto MCP is an MCP server that turns natural-language questions into focused Perfetto trace analyses, without requiring hand-written SQL. It targets Android performance work such as jank, ANR, CPU hot threads, lock contention and memory leak investigation.

Key features

  1. 01Natural language to PerfettoSQL queries
  2. 02ANR detection and root cause analysis
  3. 03Thread-level CPU utilization profiling
  4. 04Jank frame detection and frame summaries
  5. 05Binder and thread contention analysis

Use cases

  1. 01Finding out why a process spends long periods on a task in a trace
  2. 02Investigating ANR events and their severity in an Android trace
  3. 03Locating main-thread hotspots and memory growth signals

MCP support

The project runs as an MCP server and exposes analysis tools such as find_slices, execute_sql_query, detect_anrs, detect_jank_frames and memory_leak_detector, which return structured JSON results to MCP clients.

#perfetto#android-performance#perfetto-analysis#anr-detection#jank-frame-detection#memory-profiler#binder-profiler

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "perfetto": {
      "command": "uvx",
      "args": [
        "perfetto-mcp"
      ]
    }
  }
}
Run commanduvx perfetto-mcp

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
pypiperfetto-mcp

Tools

12

Saved tool list · updated 2w ago

ParameterTypeRequiredDescription
limitintegerNo
main_thread_onlybooleanNo
match_modestringNo
patternstringYes
process_nameanyNo
time_rangeanyNo
trace_pathstringYes

Details

From the project README

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"]
Optional: Use a Local trace_processor_shell Binary

If your network environment blocks downloads, set PERFETTO_MCP_TRACE_PROCESSOR_BIN_PATH to an absolute path of a local trace_processor_shell binary.

When this env var is set, perfetto-mcp uses that binary directly. When it is not set, default perfetto Python behavior is unchanged.

Example (mcp.json):

{
  "mcpServers": {
    "perfetto-mcp": {
      "command": "uvx",
      "args": ["perfetto-mcp"],
      "env": {
        "PERFETTO_MCP_TRACE_PROCESSOR_BIN_PATH": "D:/tools/perfetto/trace_processor_shell.exe"
      }
    }
  }
}

Example (~/.codex/config.toml):

[mcp_servers.perfetto-mcp]
command = "uvx"
args = ["perfetto-mcp"]
[mcp_servers.perfetto-mcp.env]
PERFETTO_MCP_TRACE_PROCESSOR_BIN_PATH = "D:/tools/perfetto/trace_processor_shell.exe"
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

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.