JinDaGe - perfetto-mcp MCP Details

article

README

🚀 Perfetto MCP

将自然语言转化为强大的Perfetto跟踪分析工具

Perfetto MCP是一个模型上下文协议（MCP）服务器，它能够将自然语言提示转化为针对性的Perfetto分析。无需编写SQL，就能快速解释卡顿现象、诊断应用程序无响应（ANR）事件、找出CPU热点线程、发现锁竞争问题以及检测内存泄漏。

✨ 主要特性

自然语言转SQL：用简洁的英语提问，即可获得精确的Perfetto查询。
ANR检测：自动识别并分析应用程序无响应（ANR）事件。
性能分析：包括CPU性能分析、帧卡顿检测和内存泄漏检测。
线程竞争分析：找出同步瓶颈和锁竞争问题。
Binder性能分析：分析进程间通信（IPC）性能和缓慢的系统交互。

til

📋 前置要求

Python 3.13+（macOS/Homebrew）：
```
brew install python@3.13
```
uv（推荐）：
```
brew install uv
```

🚀 快速开始

Cursor

或者添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目）：

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

Claude Code

运行以下命令。更多信息请参考 Claude Code MCP文档。

# 添加到用户范围
claude mcp add perfetto-mcp --scope user -- uvx perfetto-mcp

或者编辑 ~/claude.json（macOS）或 %APPDATA%\Claude\claude.json（Windows）：

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

VS Code

或者添加到 .vscode/mcp.json（项目）或运行 “MCP: 添加服务器” 命令：

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

在GitHub Copilot Chat的代理模式中启用。

Codex

编辑 ~/.codex/config.toml：

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

本地安装（开发服务器）

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

本地MCP

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

使用pip安装

```bash pip3 install perfetto-mcp python3 -m perfetto_mcp ```

📖 如何使用

示例起始提示：

在Perfetto跟踪中，我发现FragmentManager执行耗时438ms。你能找出耗时如此之久的原因吗？

必需参数

每个工具都需要以下两个输入： | 参数 | 描述 | 示例 | |-----------|-------------|---------| | trace_path | Perfetto跟踪文件的绝对路径 | /path/to/trace.perfetto-trace | | process_name | 目标进程/应用名称 | com.example.app |

在你的提示中

明确指定跟踪文件和进程，在提示前加上： "使用Perfetto跟踪文件 /absolute/path/to/trace.perfetto-trace 分析进程 com.example.app"

可选过滤器

许多工具支持额外的过滤条件（可让大语言模型处理）：

time_range：{start_ms: 10000, end_ms: 25000}
特定工具的阈值：min_block_ms、jank_threshold_ms、limit

🛠️ 可用工具

🔎 探索与发现

| 工具 | 用途 | 示例提示 | |------|---------|----------------| | find_slices | 查看切片名称并定位热点路径 | "查找包含 'Choreographer' 的切片名称并展示前几个示例" | | execute_sql_query | 运行自定义PerfettoSQL进行高级分析 | "运行自定义SQL以关联前30秒内的线程和帧" |

🚨 ANR分析

注意：如果记录的跟踪文件包含ANR事件，此功能将非常有用。 | 工具 | 用途 | 示例提示 | |------|---------|----------------| | detect_anrs | 查找ANR事件并进行严重程度分类 | "检测前10秒内的ANR事件并总结严重程度" | | anr_root_cause_analyzer | 深入分析ANR原因并按可能性排序 | "分析20,000ms左右的ANR根本原因并对可能的原因进行排序" |

🎯 性能分析

| 工具 | 用途 | 示例提示 | |------|---------|----------------| | cpu_utilization_profiler | 线程级CPU使用情况和调度分析 | "按线程分析CPU使用情况并标记热点线程" | | main_thread_hotspot_slices | 找出主线程中运行时间最长的操作 | "列出10秒至25秒内主线程中耗时超过50ms的热点操作" |

📱 UI性能分析

| 工具 | 用途 | 示例提示 | |------|---------|----------------| | detect_jank_frames | 识别未按时完成的帧 | "找出耗时超过16.67ms的卡顿帧并列出最严重的20个" | | frame_performance_summary | 总结帧性能指标 | "总结帧性能并报告卡顿率和P99 CPU时间" |

🔒 并发与IPC分析

| 工具 | 用途 | 示例提示 | |------|---------|----------------| | thread_contention_analyzer | 找出同步瓶颈 | "找出15秒至30秒内的锁竞争问题并展示最严重的等待情况" | | binder_transaction_profiler | 分析Binder IPC性能 | "分析缓慢的Binder事务并按服务器进程分组" |

💾 内存分析

| 工具 | 用途 | 示例提示 | |------|---------|----------------| | memory_leak_detector | 检测持续的内存增长模式 | "检测最后60秒内的内存泄漏信号" | | heap_dominator_tree_analyzer | 找出占用大量内存的类 | "分析堆主导类并列出占用内存最多的类" |

输出格式

所有工具都返回结构化的JSON数据，包含：

摘要：高层次的分析结果。
详情：特定工具的分析结果。
元数据：执行上下文和使用的任何回退信息。

📚 资源

跟踪处理器Python API - Perfetto的Python接口。
Perfetto SQL语法 - 自定义查询的SQL参考。

📄 许可证

本项目采用Apache 2.0许可证。详情请参考 LICENSE。

GitHub • 问题反馈 • 文档

perfetto-mcp