instruments

InstrumentsMCP is an MCP server that enables AI agents to control Instruments-based profiling for iOS and macOS apps through a consolidated MCP interface. The server exposes a set of profiling tools accessible via the instrumentsmcp CLI, including hands-free UI automation, CLI recording, and agent-driven profiling workflows. With this server running, agents can start, stop, and analyze traces, drive UI interactions via AXe CLI, and request structured profiling results for CPU, memory, leaks, and other performance aspects. The CLI commands supported by the package include recording sessions, starting and stopping profiling, and running scenario-based captures that combine interactions (taps, gestures, text input) with profiling templates like Time Profiler. The server is designed to produce structured findings and trace outputs that agents can parse to provide actionable recommendations.

Typical workflows include:

• Recording a target app with a Time Profiler template using instrumentsmcp record --process MyApp --template "Time Profiler" and then stopping the recording to generate a trace.
• Driving UI interactions via the agent by using profile_scenario with a sequence of actions (launch, wait, gesture, tap, type_text, snapshot_ui) and receiving a structured report with hotspots and severities.
• Performing one-shot profiling (profile_leaks, profile_memory, profile_cpu, etc.) for quick checks without building a full scenario.

To use from code or an agent, connect to the MCP server, invoke the appropriate MCP commands, and parse the returned structured results for prioritization and automated fixes.

Prerequisites:

• Node.js v20 or newer installed on the host machine.
• npm (comes with Node.js).

Installation steps:

1. Install the MCP server package globally (recommended): npm install -g instrumentsmcp

2. Verify installation and access the CLI: instrumentsmcp --help

3. Start the MCP server via the configured mcp_config (as defined in this repository): The MCP server can be started through your MCP runner using the provided configuration: { "mcp_config": { "mcpServers": { "instruments": { "command": "npx", "args": ["-y", "instrumentsmcp"] } } } }

4. Optional: If you prefer not to install globally, you can run the server locally with npx without the -g flag: npx -y instrumentsmcp

Notes:

• Ensure Xcode and Instruments tooling are installed on macOS for Instruments-based profiling.
• Some commands may require additional accessibility permissions or simulator/device setup.

Tips and common issues:

• Accessibility identifiers: The profiling workflow benefits significantly from elements having accessibilityIdentifier values to allow the agent to drive interactions reliably.
• If you encounter permission prompts when interacting with simulators, ensure the terminal/IDE has necessary accessibility and automation permissions on macOS.
• When using profile_scenario, a well-formed sequence of actions (launch, wait, tap/type, and snapshot) yields the most actionable results.
• Check that AXe CLI is installed and available in PATH if you rely on UI automation (as described in the InstrumentsMCP docs).
• Output traces and analysis results are stored under the configured traces directory (e.g., ~/.instruments-mcp/traces) for reference and re-analysis.