Instruments Mcp Server

InstrumentsMCP

Profiler data for agents.

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 →](docs/tools.md)

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](docs/tools.md)
• [Example output](docs/example-output.md)
• [Prepare your app for AI-driven profiling](docs/prepare-your-app.md)

Architecture

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

Build from source

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.

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nemanjavlahovic
• Source: nemanjavlahovic/instruments-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.