perfetto

Perfetto MCP turns natural-language prompts into focused Perfetto analyses. It exposes a suite of tools for exploring trace data, diagnosing ANRs, profiling CPU usage, detecting frame jank, examining thread contention, and profiling IPC with Binder. Each tool accepts a trace path and target process name, plus optional filters such as time ranges or thresholds. When you prompt the model, you specify the trace and process, and the MCP translates your request into Perfetto queries or Python-based analyses, returning structured results that include a summary, detailed findings, and execution metadata.

Available tools cover exploration, ANR analysis, performance profiling, UI performance, concurrency and IPC, and memory analysis. Examples include find_slices for surveying hot paths, detect_anrs for ANR events, cpu_utilization_profiler for thread-level CPU insights, frame_performance_summary for overall frame health, thread_contention_analyzer for lock contention, and memory_leak_detector for growth signals. The output format is a consistent JSON structure with Summary, Details, and Metadata, making it easy to chain analyses or present results in dashboards.

Prerequisites:

• Python 3.13+ (recommended 3.13)
• uv (recommended)
• Optional: Pip for Python package installation

Install options:

1. Install and run via pip (recommended for quick start):

pip3 install perfetto-mcp
python3 -m perfetto_mcp

This starts the development MCP server (port and exact invocation depend on your environment).

2. Run with uvx (local development workflow):

# Ensure uvx is installed (per prerequisites, e.g., via Homebrew on macOS)
uv sync
uv run mcp dev src/perfetto_mcp/dev.py

If you follow this path, you may need to set PYTHONPATH for local modules:

export PYTHONPATH=src
uv run mcp dev src/perfetto_mcp/dev.py

3. Add a server entry for Cursor or IDE integrations (example):

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

Prerequisites recap:

• Install Python 3.13+
• Install uv (recommended) or use an alternative runner
• Install the perfetto-mcp package if using pip
• Ensure paths (e.g., PYTHONPATH) are set consistent with your local install

Tips and common issues:

• If using uv/run for local development, ensure the module path (src) is in PYTHONPATH so imports resolve correctly.
• When running with Cursor or IDE integrations, align the mcpServers entry (name, command, and args) with your local startup command (e.g., uvx perfetto-mcp or uv run ...).
• The MCP outputs structured JSON with Summary, Details, and Metadata. Use the Details field for in-depth results and follow up prompts with the same trace and process context.
• Environment variables can be used to customize paths, trace locations, or logging levels (e.g., PYTHONPATH, TRACE_PATH, LOG_LEVEL).
• If you encounter Perfetto-specific errors, verify that the trace format is compatible and that the required Perfetto tools are accessible in the environment where the MCP runs.