# Instruments Mcp Server

> MCP server for Xcode Instruments — AI agents get structured performance profiling (CPU, SwiftUI, memory, hitches) instead of raw xctrace XML

- **Type:** MCP server
- **Install:** `agentstack add mcp-nemanjavlahovic-instruments-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [nemanjavlahovic](https://agentstack.voostack.com/s/nemanjavlahovic)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [nemanjavlahovic](https://github.com/nemanjavlahovic)
- **Source:** https://github.com/nemanjavlahovic/instruments-mcp-server

## Install

```sh
agentstack add mcp-nemanjavlahovic-instruments-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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`:

```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](https://github.com/cameroncooke/AXe) (`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:

```bash
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

```bash
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](https://github.com/nemanjavlahovic)
- **Source:** [nemanjavlahovic/instruments-mcp-server](https://github.com/nemanjavlahovic/instruments-mcp-server)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-nemanjavlahovic-instruments-mcp-server
- Seller: https://agentstack.voostack.com/s/nemanjavlahovic
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.