# Perfetto Mcp

> This is a Model Context Protocol (MCP) server that gets answers from your Perfetto Traces. It turns natural‑language prompts into focused Perfetto analyses.

- **Type:** MCP server
- **Install:** `agentstack add mcp-antarikshc-perfetto-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [antarikshc](https://agentstack.voostack.com/s/antarikshc)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [antarikshc](https://github.com/antarikshc)
- **Source:** https://github.com/antarikshc/perfetto-mcp

## Install

```sh
agentstack add mcp-antarikshc-perfetto-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

## 📋 Prerequisites

- **Python 3.13+** (macOS/Homebrew):
  ```bash
  brew install python@3.13
  ```
- **uv** (recommended):
  ```bash
  brew install uv
  ```

## 🚀 Getting Started

Cursor

[](https://cursor.com/install-mcp?name=perfetto-mcp&config=eyJjb21tYW5kIjoidXZ4IHBlcmZldHRvLW1jcCJ9)

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

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

Claude Code

Run this command. See [Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp) for more info.

```bash
# 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):

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

VS Code

[](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22perfetto-mcp%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22perfetto-mcp%22%5D%7D)

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

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

Enable in GitHub Copilot Chat's Agent mode.

Codex

Edit `~/.codex/config.toml`:

```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`):

```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`):

```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)

```bash
cd perfetto-mcp-server
uv sync
uv run mcp dev src/perfetto_mcp/dev.py
```

Local MCP

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

Using pip

```bash
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:

| Parameter | Description | Example |
|-----------|-------------|---------|
| **trace_path** | Absolute path to your Perfetto trace | `/path/to/trace.perfetto-trace` |
| **process_name** | Target process/app name | `com.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

| Tool | Purpose | Example Prompt |
|------|---------|----------------|
| **`find_slices`** | Survey slice names and locate hot paths | *"Find slice names containing 'Choreographer' and show top examples"* |
| **`execute_sql_query`** | Run 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

| Tool | Purpose | Example Prompt |
|------|---------|----------------|
| **`detect_anrs`** | Find ANR events with severity classification | *"Detect ANRs in the first 10s and summarize severity"* |
| **`anr_root_cause_analyzer`** | Deep-dive ANR causes with ranked likelihood | *"Analyze ANR root cause around 20,000 ms and rank likely causes"* |

### 🎯 Performance Profiling

| Tool | Purpose | Example Prompt |
|------|---------|----------------|
| **`cpu_utilization_profiler`** | Thread-level CPU usage and scheduling | *"Profile CPU usage by thread and flag the hottest threads"* |
| **`main_thread_hotspot_slices`** | Find longest-running main thread operations | *"List main-thread hotspots >50 ms during 10s–25s"* |

### 📱 UI Performance

| Tool | Purpose | Example Prompt |
|------|---------|----------------|
| **`detect_jank_frames`** | Identify frames missing deadlines | *"Find janky frames above 16.67 ms and list the worst 20"* |
| **`frame_performance_summary`** | Overall frame health metrics | *"Summarize frame performance and report jank rate and P99 CPU time"* |

### 🔒 Concurrency & IPC

| Tool | Purpose | Example Prompt |
|------|---------|----------------|
| **`thread_contention_analyzer`** | Find synchronization bottlenecks | *"Find lock contention between 15s–30s and show worst waits"* |
| **`binder_transaction_profiler`** | Analyze Binder IPC performance | *"Profile slow Binder transactions and group by server process"* |

### 💾 Memory Analysis

| Tool | Purpose | Example Prompt |
|------|---------|----------------|
| **`memory_leak_detector`** | Find sustained memory growth patterns | *"Detect memory-leak signals over the last 60s"* |
| **`heap_dominator_tree_analyzer`** | Identify 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

- **[Trace Processor Python API](https://perfetto.dev/docs/analysis/trace-processor-python)** - Perfetto's Python interface
- **[Perfetto SQL Syntax](https://perfetto.dev/docs/analysis/perfetto-sql-syntax)** - SQL reference for custom queries

## 📄 License

Apache 2.0 License. See [LICENSE](https://github.com/antarikshc/perfetto-mcp/blob/main/LICENSE) for details.

---

  GitHub •
  Issues •
  Documentation

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [antarikshc](https://github.com/antarikshc)
- **Source:** [antarikshc/perfetto-mcp](https://github.com/antarikshc/perfetto-mcp)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-antarikshc-perfetto-mcp
- Seller: https://agentstack.voostack.com/s/antarikshc
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.