InstrumentsMCP

<p align="center"> <img src="instrumentsmcp-icon.svg" alt="InstrumentsMCP icon" width="152" /> </p>

<h1 align="center">InstrumentsMCP</h1>

<p align="center"> <strong>Profiler data for agents.</strong> </p>

<p align="center"> <a href="https://www.npmjs.com/package/instrumentsmcp"><img src="https://img.shields.io/npm/v/instrumentsmcp" alt="npm"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a> <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node.js"></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-purple" alt="MCP"></a> </p>

MCP server that wraps Xcode Instruments. Record traces, automate the simulator, and return structured profiling data your coding agent can act on.

Quick Start

Requirements: macOS, Xcode, Node.js >= 20

Add to your project's .mcp.json:

{
  "mcpServers": {
    "instruments": {
      "command": "npx",
      "args": ["-y", "instrumentsmcp@latest"]
    }
  }
}

Or run directly: npx instrumentsmcp@latest

Works with Claude Code, Cursor, Windsurf, and any MCP client.

What It Does

Ask your agent to profile. It records a trace, drives the simulator, and returns structured results:

=== Time Profiler ===  severity: [WARNING]  samples: 1587

Hotspots:
  UpdateStack::update() (AttributeGraph)  42.3ms self ━━━━━━╌╌╌╌╌╌╌╌╌ 12.1%
  FeedViewModel.loadItems() (MyApp)        28.1ms self ━━━━╌╌╌╌╌╌╌╌╌╌╌ 8.0%

Main thread blockers:
  [WARNING] FeedViewModel.loadItems()  28.1ms

35 tools across profiling, UI automation, simulator control, and trace analysis. Full tool list →

Profiling

• One-shot — profile_cpu, profile_swiftui, profile_memory, profile_hitches, profile_launch, profile_energy, profile_leaks, profile_network
• Scripted scenarios — profile_scenario records a trace while executing UI steps (tap, scroll, type, launch)
• Interactive — start_profiling / stop_profiling for manual interaction
• Health check — performance_audit runs 5 templates and combines the results
• Any template — profile_raw handles templates without a dedicated parser

UI Automation

Drive the simulator programmatically: ui_tap, ui_type, ui_swipe, ui_gesture, ui_snapshot, ui_long_press. Powered by AXe CLI (brew tap cameroncooke/axe && brew install axe).

Simulator Control

Launch/terminate apps, open deep links, push notifications, take screenshots, set location, toggle dark mode.

Analysis

Re-analyze saved traces, drill into specific functions, track regressions with baselines, generate Markdown reports.

CLI Mode

Record traces from the terminal without an MCP client:

npx instrumentsmcp record --process MyApp
npx instrumentsmcp record --process MyApp --template Allocations

Ctrl+C to stop. Feed the trace to your agent for analysis.

Compatibility

• Xcode Instruments (xctrace) 15.x through 26.x
• Handles xctrace 26 Deferred recording mode automatically
• Device identifiers (booted, device name, UDID) resolved automatically

Docs

• Full tool reference
• Example output
• Prepare your app for AI-driven profiling

<details> <summary><b>Architecture</b></summary>

src/
├── index.ts              # MCP server entry + CLI router
├── cli.ts                # CLI mode (instrumentsmcp record)
├── tools/
│   ├── profile.ts        # One-shot profiling tools
│   ├── simulator.ts      # Simulator control + start/stop + scenarios
│   ├── analyze.ts        # Trace analysis + symbolication + audit
│   ├── baseline.ts       # Baseline comparison + report generation
│   ├── investigate.ts    # Drill-down + trace listing
│   ├── ui.ts             # UI automation (snapshot, tap, type, swipe)
│   └── list.ts           # Discovery tools (status, templates, devices)
├── parsers/              # Template-specific XML→JSON parsers
└── utils/                # xctrace, simctl, AXe wrappers + shared helpers

</details>

<details> <summary><b>Build from source</b></summary>

git clone https://github.com/nemanjavlahovic/instruments-mcp-server.git
cd instruments-mcp-server
npm install && npm run build

Point your MCP client to dist/index.js.

</details>

License

MIT