Perfetto MCP

将自然语言转化为强大的 Perfetto 追踪分析

一个模型上下文协议 (MCP) 服务器，可将自然语言提示词转换为针对性的 Perfetto 分析。无需编写 SQL，即可快速解释卡顿、诊断 ANR、定位 CPU 热点线程、发现锁竞争并查找内存泄漏。

✨ 功能特性

• 自然语言 → SQL：用简单的英语提问，获取精确的 Perfetto 查询

• ANR 检测：自动识别并分析“应用无响应”(ANR) 事件

• 性能分析：CPU 分析、帧卡顿检测、内存泄漏检测

• 线程竞争：查找同步瓶颈和锁竞争

• Binder 分析：分析 IPC 性能和缓慢的系统交互

📋 前置要求

• Python 3.13+ (macOS/Homebrew)：

  brew install python@3.13

• uv (推荐)：

  brew install uv

🚀 快速开始

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

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

运行此命令。更多信息请参阅 Claude Code MCP 文档。

# Add to user scope
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"]
    }
  }
}

或者添加到 .vscode/mcp.json (项目) 或运行 "MCP: Add Server" 命令：

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

在 GitHub Copilot Chat 的 Agent 模式中启用。

编辑 ~/.codex/config.toml：

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

可选：使用本地 trace_processor_shell 二进制文件

如果您的网络环境阻止下载，请将 PERFETTO_MCP_TRACE_PROCESSOR_BIN_PATH 设置为本地 trace_processor_shell 二进制文件的绝对路径。

设置此环境变量后，perfetto-mcp 将直接使用该二进制文件。如果不设置，则保持默认的 perfetto Python 行为。

示例 (mcp.json)：

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

示例 (~/.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"

本地安装 (开发服务器)

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

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

pip3 install perfetto-mcp
python3 -m perfetto_mcp

📖 如何使用

示例起始提示词：

在 perfetto 追踪中，我看到 FragmentManager 执行耗时 438ms。你能找出为什么它耗时这么长吗？

必需参数

每个工具都需要这两个输入：

在提示词中

请明确指定追踪文件和进程，在提示词前加上：

"使用 perfetto 追踪 /absolute/path/to/trace.perfetto-trace 处理进程 com.example.app"

可选过滤器

许多工具支持额外的过滤（让您的 LLM 处理即可）：

• time_range: {start_ms: 10000, end_ms: 25000}

• 工具特定阈值: min_block_ms, jank_threshold_ms, limit

🛠️ 可用工具

🔎 探索与发现

🚨 ANR 分析

注意：如果记录的追踪包含 ANR，此功能很有用

🎯 性能分析

📱 UI 性能

🔒 并发与 IPC

💾 内存分析

输出格式

所有工具均返回结构化的 JSON，包含：

• Summary: 高级发现

• Details: 工具特定结果

• Metadata: 执行上下文及使用的任何回退方案

📚 资源

• Trace Processor Python API - Perfetto 的 Python 接口

• Perfetto SQL Syntax - 自定义查询的 SQL 参考

📄 许可证

Apache 2.0 许可证。详情请参阅 LICENSE。