ios-instruments-mcp

MCP server that wraps xctrace (Instruments) to profile iOS apps directly from Claude. Ask natural language questions about your app's performance and get actionable answers.

What you can ask Claude

"Faz o launch timer do com.myapp.ios e diz-me os ofensores"
"Analisa o memory footprint do app no simulador"
"Verifica se há leaks de memória no com.myapp.ios"
"Qual função está a consumir mais CPU?"
"Há requests de rede lentos no app?"
"Analisa o trace em ~/Desktop/launch.xctrace"

Requirements

• macOS with Xcode installed
• Xcode Command Line Tools: xcode-select --install
• Node.js ≥ 18

Setup

# 1. Clone and install
git clone https://github.com/bfernandesbfs/ios-instruments-mcp.git
cd ios-instruments-mcp
npm install
npm run build

# 2. Register in Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ios-instruments": {
      "command": "node",
      "args": ["/absolute/path/to/ios-instruments-mcp/build/index.js"]
    }
  }
}

Restart Claude Desktop after saving.

Available Tools

Tool	Template	Description
list_devices	—	Lists simulators and physical devices
list_templates	—	Lists all Instruments templates on this Mac
analyze_launch	App Launch	Records + analyzes app startup time
analyze_launch_trace	App Launch	Analyzes an existing .xctrace file
analyze_allocations	Allocations	Peak memory, top allocation types
analyze_allocations_trace	Allocations	Analyzes an existing .xctrace file
analyze_leaks	Leaks	Memory leak detection with retain cycle info
analyze_leaks_trace	Leaks	Analyzes an existing .xctrace file
analyze_time_profiler	Time Profiler	CPU hot methods and main thread usage
analyze_time_profiler_trace	Time Profiler	Analyzes an existing .xctrace file
analyze_network	Network	Slow requests, transfer sizes, status codes
analyze_network_trace	Network	Analyzes an existing .xctrace file

Example output (App Launch)

# App Launch Analysis — com.myapp.ios

⚠️ Launch time 1240ms — above 400ms. Users may notice the delay.

**Total:** 1240ms

## Phases
- pre-main (dyld + static init): 434ms (35%)
- post-main (AppDelegate + UI): 806ms (65%)

## Top Offenders

🔴 `-[DatabaseManager setup]` [post-main]
   Self: 540ms | Total: 540ms | 43%
   💡 Move database initialization to a background queue or use lazy loading.

🟡 `+[AnalyticsSDK configure:]` [post-main]
   Self: 210ms | Total: 210ms | 17%
   💡 Defer analytics SDK initialization after first frame is rendered.

## Recommendations
- Fix 1 critical offender(s) — each adds 300ms+ to launch.
- Target: total launch under 400ms.

Notes

• Physical devices require Enable UI Automation in Settings → Developer
• Temp .xctrace files are cleaned up automatically after each run
• The parser handles both legacy and modern xctrace XML formats
• All tools have an _trace variant for analyzing files you already have on disk

License

MIT