servers / instruments-mcp-server
instruments-mcp-server
communitystdiolocaldestructive capablehealthy
MCP server for Xcode Instruments — AI agents get structured performance profiling (CPU, SwiftUI, memory, hitches) instead of raw xctrace XML
01Tools · 29
How to read this: tool names here are observed from a live tools/list handshake. The Risk label is a heuristic inferred from the tool name (write/destructive verbs), not from executing the tool — a conservative guess, not a verified capability. We never escalate risk from a description. Found one that's wrong? Tell us — we fix on report.
| Tool | Risk | Side effects | Approval |
|---|---|---|---|
| profile_hitches Record and analyze animation hitches and main thread hangs.
Returns: Hang events by severity, worst hangs with backtraces.
Best used during scrolling or animations. Pass trace_path to re-analyze an existing trace. | read | false | unknown |
| profile_cpu Record and analyze CPU performance using Time Profiler.
Returns: Top CPU hotspots with severity classification and actionable summary.
Pass trace_path to re-analyze an existing trace without re-recording. | read | false | unknown |
| profile_launch Record and analyze app launch performance.
Returns: Total launch time, launch type (cold/warm/resume), phase breakdown, severity against Apple's guidelines.
IMPORTANT: Use launch_path to launch the app — attaching to a running process won't capture the launch.
Pass trace_path to re-analyze an existing trace. | read | false | unknown |
| profile_raw Record a trace with any Instruments template and return the raw table of contents.
Use this for templates without a dedicated parser (System Trace, File Activity, etc.).
You can then use analyze_trace to export specific tables. | unknown | unknown | unknown |
| instruments_list_instruments List all available individual instruments that can be combined into custom recordings | read | false | unknown |
| profile_swiftui Record and analyze SwiftUI view performance.
Returns: View body evaluation counts, excessive re-renders, and duration per view.
Best used while navigating through the app. Pass trace_path to re-analyze an existing trace. | read | false | unknown |
| profile_energy Record and analyze energy usage using Energy Log.
Returns: Energy impact scores (0–20 scale), per-component breakdown (CPU, GPU, network, display), thermal state.
Best results on physical devices. Pass trace_path to re-analyze an existing trace. | read | false | unknown |
| profile_memory Record and analyze memory allocations.
Returns: Allocation counts by category, total memory, largest allocators.
Pass trace_path to re-analyze an existing trace. | read | false | unknown |
| profile_leaks Record and detect memory leaks using the Leaks template.
Returns: Leaked object types, sizes, responsible libraries, and backtraces.
The Leaks instrument takes periodic heap snapshots — longer recordings improve detection.
Pass trace_path to re-analyze an existing trace. | read | false | unknown |
| instruments_list_templates List all available Instruments profiling templates (Time Profiler, SwiftUI, Allocations, etc.) | read | false | unknown |
| symbolicate_trace Add debug symbols to a trace file so function names are readable instead of memory addresses.
Run this if profile results show hex addresses instead of function names. | read | false | unknown |
| profile_network Record and analyze HTTP network traffic using the Network template.
Returns: Request counts, response times, error rates, per-domain breakdown, slowest requests.
Pass trace_path to re-analyze an existing trace. | read | false | unknown |
| instruments_list_devices List all available devices and simulators that can be profiled | read | false | unknown |
| instruments_status Check if Instruments (xctrace) is available on this system and return version info | read | false | unknown |
| analyze_trace Export and analyze a specific table from an existing .trace file.
Use after profile_raw to drill into specific data tables.
First call with toc=true to see available tables, then call with xpath to get data. | read | false | unknown |
| performance_report Generate a shareable Markdown performance report from profile results.
Pass the JSON output from one or more profile tools. Returns formatted Markdown
suitable for PRs, Slack, documentation, or stakeholder updates. | read | false | unknown |
| sim_open_url Open a URL or deep link on a simulator.
Use this for app navigation — simctl does not support direct tap/swipe.
The app must register the URL scheme in its Info.plist. | read | false | unknown |
| sim_set_location Set simulated GPS coordinates on a simulator.
Useful for profiling location-dependent features. | write | true | unknown |
| performance_audit Run a comprehensive performance audit by recording multiple profiles in sequence.
Records: Time Profiler + Animation Hitches + Leaks + Energy Log + Network for a full health check.
Returns a combined report with actionable findings and an overall severity.
Total recording time = 5x duration. | read | false | unknown |
| performance_baseline Save, compare, list, or delete performance baselines to track regressions over time.
- save: Store profile results as a named baseline (pass the JSON output from any profile tool)
- compare: Diff current results against a saved baseline — shows deltas and regression/improvement status
- list: Show all saved baselines
- delete: Remove a saved baseline | read | false | unknown |
| sim_terminate_app Terminate a running app on a simulator. | destructive | true | true |
| sim_list_booted List all booted iOS simulators and their installed user apps.
Returns: Device names, UDIDs, runtime versions, and installed app bundle IDs.
Use this to discover what's running before profiling. | read | false | unknown |
| sim_push_notification Send a simulated push notification to an app on a simulator.
Constructs an APS payload from title/body, or accepts a full custom payload. | write | true | unknown |
| start_profiling Start recording an Instruments trace and return immediately.
The user interacts with the app manually while recording runs in the background.
Call stop_profiling when done to end the recording and get parsed results.
This is the recommended workflow for profiling real user interactions:
1. start_profiling → agent starts recording
2. User scrolls, taps, navigates in the app
3. stop_profiling → agent stops recording, parses trace, returns performance data
Max recording time is 5 minutes (safety limit). Recording stops automatically if not stopped manually. | read | false | unknown |
| sim_launch_app Launch an app by bundle ID on a booted simulator.
Returns the process ID (PID) of the launched app. | read | false | unknown |
| sim_screenshot Take a screenshot of a simulator's screen. Saves as PNG.
Returns the file path to the saved screenshot. | read | false | unknown |
| stop_profiling Stop an active recording started by start_profiling.
Sends SIGINT to xctrace, waits for the trace to be saved, then parses and returns structured results.
Returns the same parsed performance data as the profile_* tools. | read | false | unknown |
| sim_set_appearance Toggle the simulator between light and dark mode.
Useful for testing appearance-sensitive performance (e.g., dark mode rendering). | write | true | unknown |
| profile_scenario Record an Instruments trace WHILE executing a scenario on a simulator.
This is the primary tool for profiling real user flows — it launches your app,
runs interaction steps (deep links, push notifications, waits), and records
performance data throughout.
Steps execute sequentially after xctrace starts recording.
Uses deep links (open_url) for navigation since simctl has no tap/swipe.
The app must register URL schemes in Info.plist for deep link navigation.
Returns: Parsed profile results + screenshots taken + scenario execution log. | read | false | unknown |
02Install & source
npx -y instrumentsmcp@latest
npxnpx -y instrumentsmcp
npx- repohttps://github.com/nemanjavlahovic/instruments-mcp-server
- licenseMIT
- adoption19 stars · 2 forks
05Provenance & freshness
sourcesGitHub repo search [p4]
last_checked2026-08-25 09:54Z
next_check2026-08-27 09:50Z
cadenceevery 48h
verifiedtools_list:passed handshake:passed metadata:passed
index_statusindex — 8 unique facts >= 5
06Badge
Add the “as seen on MCPExplorer” badge to your README. 
[](https://mcpexplorer.com/servers/instruments-mcp-server)
Next step
This is one server. A loadout combines the right servers, governance, and proven plays for a whole job — assembled deliberately, not tool-dumped.
Explore loadouts →