Skip to content
Back to search

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/antarikshc--perfetto-mcp/badge.svg)](/listings/antarikshc--perfetto-mcp)

HTML

<a href="/listings/antarikshc--perfetto-mcp"><img src="/api/listings/antarikshc--perfetto-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

<details> <summary><strong>Cursor</strong></summary>

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

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

</details>

<details> <summary><strong>Claude Code</strong></summary>

Run this command. See [Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp) 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"]
    }
  }
}

</details>

<details> <summary><strong>VS Code</strong></summary>

[<img alt="Install in VS Code" src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Perfetto%20MCP&color=0098FF">](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:

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

Enable in GitHub Copilot Chat's Agent mode.

</details>

<details> <summary><strong>Codex</strong></summary>

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

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

</details>

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

<details> <summary><strong>Local MCP</strong></summary>

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

</details>

<details> <summary><strong>Using pip</strong></summary>

pip3 install perfetto-mcp
python3 -m perfetto_mcp

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 281 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ![showcase](./static/perfetto-mcp-logo.jpg)
  2. # Perfetto MCP
  3. > Turn natural language into powerful Perfetto trace analysis
  4. 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.
  5. ## ✨ Features
  6. - **Natural Language → SQL**: Ask questions in plain English, get precise Perfetto queries
  7. - **ANR Detection**: Automatically identify and analyze Application Not Responding events
  8. - **Performance Analysis**: CPU profiling, frame jank detection, memory leak detection
  9. - **Thread Contention**: Find synchronization bottlenecks and lock contention
  10. - **Binder Profiling**: Analyze IPC performance and slow system interactions
  11. ![showcase](./static/Perfetto-mcp-showcase.gif)
  12. ## 📋 Prerequisites
  13. - **Python 3.13+** (macOS/Homebrew):
  14. ```bash
  15. brew install python@3.13
  16. ```
  17. - **uv** (recommended):
  18. ```bash
  19. brew install uv
  20. ```
  21. ## 🚀 Getting Started
  22. <details>
  23. <summary><strong>Cursor</strong></summary>
  24. [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=perfetto-mcp&config=eyJjb21tYW5kIjoidXZ4IHBlcmZldHRvLW1jcCJ9)
  25. Or add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
  26. ```json
  27. {
  28. "mcpServers": {
  29. "perfetto-mcp": {
  30. "command": "uvx",
  31. "args": ["perfetto-mcp"]
  32. }
  33. }
  34. }
  35. ```
  36. </details>
  37. <details>
  38. <summary><strong>Claude Code</strong></summary>
  39. Run this command. See [Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp) for more info.
  40. ```bash
  41. # Add to user scope
  42. claude mcp add perfetto-mcp --scope user -- uvx perfetto-mcp
  43. ```
  44. Or edit `~/claude.json` (macOS) or `%APPDATA%\Claude\claude.json` (Windows):
  45. ```json
  46. {
  47. "mcpServers": {
  48. "perfetto-mcp": {
  49. "command": "uvx",
  50. "args": ["perfetto-mcp"]
  51. }
  52. }
  53. }
  54. ```
  55. </details>
  56. <details>
  57. <summary><strong>VS Code</strong></summary>
  58. [<img alt="Install in VS Code" src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Perfetto%20MCP&color=0098FF">](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)
  59. or add to `.vscode/mcp.json` (project) or run "MCP: Add Server" command:
  60. ```json
  61. {
  62. "mcpServers": {
  63. "perfetto-mcp": {
  64. "command": "uvx",
  65. "args": ["perfetto-mcp"]
  66. }
  67. }
  68. }
  69. ```
  70. Enable in GitHub Copilot Chat's Agent mode.
  71. </details>
  72. <details>
  73. <summary><strong>Codex</strong></summary>
  74. Edit `~/.codex/config.toml`:
  75. ```toml
  76. [mcp_servers.perfetto-mcp]
  77. command = "uvx"
  78. args = ["perfetto-mcp"]
  79. ```
  80. </details>
  81. ### Optional: Use a Local `trace_processor_shell` Binary
  82. If your network environment blocks downloads, set
  83. `PERFETTO_MCP_TRACE_PROCESSOR_BIN_PATH` to an absolute path of a local
  84. `trace_processor_shell` binary.
  85. When this env var is set, `perfetto-mcp` uses that binary directly.
  86. When it is not set, default `perfetto` Python behavior is unchanged.
  87. Example (`mcp.json`):
  88. ```json
  89. {
  90. "mcpServers": {
  91. "perfetto-mcp": {
  92. "command": "uvx",
  93. "args": ["perfetto-mcp"],
  94. "env": {
  95. "PERFETTO_MCP_TRACE_PROCESSOR_BIN_PATH": "D:/tools/perfetto/trace_processor_shell.exe"
  96. }
  97. }
  98. }
  99. }
  100. ```
  101. Example (`~/.codex/config.toml`):
  102. ```toml
  103. [mcp_servers.perfetto-mcp]
  104. command = "uvx"
  105. args = ["perfetto-mcp"]
  106. [mcp_servers.perfetto-mcp.env]
  107. PERFETTO_MCP_TRACE_PROCESSOR_BIN_PATH = "D:/tools/perfetto/trace_processor_shell.exe"
  108. ```
  109. ### Local Install (development server)
  110. ```bash
  111. cd perfetto-mcp-server
  112. uv sync
  113. uv run mcp dev src/perfetto_mcp/dev.py
  114. ```
  115. <details>
  116. <summary><strong>Local MCP</strong></summary>
  117. ```json
  118. {
  119. "mcpServers": {
  120. "perfetto-mcp-local": {
  121. "command": "uv",
  122. "args": [
  123. "--directory",
  124. "/path/to/git/repo/perfetto-mcp",
  125. "run",
  126. "-m",
  127. "perfetto_mcp"
  128. ],
  129. "env": { "PYTHONPATH": "src" }
  130. }
  131. }
  132. }
  133. ```
  134. </details>
  135. <details>
  136. <summary><strong>Using pip</strong></summary>
  137. ```bash
  138. pip3 install perfetto-mcp
  139. python3 -m perfetto_mcp
  140. ```
  141. </details>
  142. ## 📖 How to Use
  143. Example starting prompt:
  144. > In the perfetto trace, I see that the FragmentManager is taking 438ms to execute. Can you figure out why it's taking so long?
  145. ### Required Parameters
  146. Every tool needs these two inputs:
  147. | Parameter | Description | Example |
  148. |-----------|-------------|---------|
  149. | **trace_path** | Absolute path to your Perfetto trace | `/path/to/trace.perfetto-trace` |
  150. | **process_name** | Target process/app name | `com.example.app` |
  151. ### In Your Prompts
  152. Be explicit about the trace and process, prefix your prompt with:
  153. *"Use perfetto trace `/absolute/path/to/trace.perfetto-trace` for process `com.example.app`"*
  154. ### Optional Filters
  155. Many tools support additional filtering (but let your LLM handle that):
  156. - **time_range**: `{start_ms: 10000, end_ms: 25000}`
  157. - **Tool-specific thresholds**: `min_block_ms`, `jank_threshold_ms`, `limit`
  158. ## 🛠️ Available Tools
  159. ### 🔎 Exploration & Discovery
  160. | Tool | Purpose | Example Prompt |
  161. |------|---------|----------------|
  162. | **`find_slices`** | Survey slice names and locate hot paths | *"Find slice names containing 'Choreographer' and show top examples"* |
  163. | **`execute_sql_query`** | Run custom PerfettoSQL for advanced analysis | *"Run custom SQL to correlate threads and frames in the first 30s"* |
  164. ### 🚨 ANR Analysis
  165. Note: Helpful if the recorded trace contains ANR
  166. | Tool | Purpose | Example Prompt |
  167. |------|---------|----------------|
  168. | **`detect_anrs`** | Find ANR events with severity classification | *"Detect ANRs in the first 10s and summarize severity"* |
  169. | **`anr_root_cause_analyzer`** | Deep-dive ANR causes with ranked likelihood | *"Analyze ANR root cause around 20,000 ms and rank likely causes"* |
  170. ### 🎯 Performance Profiling
  171. | Tool | Purpose | Example Prompt |
  172. |------|---------|----------------|
  173. | **`cpu_utilization_profiler`** | Thread-level CPU usage and scheduling | *"Profile CPU usage by thread and flag the hottest threads"* |
  174. | **`main_thread_hotspot_slices`** | Find longest-running main thread operations | *"List main-thread hotspots >50 ms during 10s–25s"* |
  175. ### 📱 UI Performance
  176. | Tool | Purpose | Example Prompt |
  177. |------|---------|----------------|
  178. | **`detect_jank_frames`** | Identify frames missing deadlines | *"Find janky frames above 16.67 ms and list the worst 20"* |
  179. | **`frame_performance_summary`** | Overall frame health metrics | *"Summarize frame performance and report jank rate and P99 CPU time"* |
  180. ### 🔒 Concurrency & IPC
  181. | Tool | Purpose | Example Prompt |
  182. |------|---------|----------------|
  183. | **`thread_contention_analyzer`** | Find synchronization bottlenecks | *"Find lock contention between 15s–30s and show worst waits"* |
  184. | **`binder_transaction_profiler`** | Analyze Binder IPC performance | *"Profile slow Binder transactions and group by server process"* |
  185. ### 💾 Memory Analysis
  186. | Tool | Purpose | Example Prompt |
  187. |------|---------|----------------|
  188. | **`memory_leak_detector`** | Find sustained memory growth patterns | *"Detect memory-leak signals over the last 60s"* |
  189. | **`heap_dominator_tree_analyzer`** | Identify memory-hogging classes | *"Analyze heap dominator classes and list top offenders"* |
  190. ### Output Format
  191. All tools return structured JSON with:
  192. - **Summary**: High-level findings
  193. - **Details**: Tool-specific results
  194. - **Metadata**: Execution context and any fallbacks used
  195. ## 📚 Resources
  196. - **[Trace Processor Python API](https://perfetto.dev/docs/analysis/trace-processor-python)** - Perfetto's Python interface
  197. - **[Perfetto SQL Syntax](https://perfetto.dev/docs/analysis/perfetto-sql-syntax)** - SQL reference for custom queries
  198. ## 📄 License
  199. Apache 2.0 License. See [LICENSE](https://github.com/antarikshc/perfetto-mcp/blob/main/LICENSE) for details.
  200. ---
  201. <p align="center">
  202. <a href="https://github.com/antarikshc/perfetto-mcp">GitHub</a> •
  203. <a href="https://github.com/antarikshc/perfetto-mcp/issues">Issues</a> •
  204. <a href="https://github.com/antarikshc/perfetto-mcp/blob/main/README-internal.md">Documentation</a>
  205. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.