XCode CLI MCP: Convenience wrapper for Xcode CLI tools & iOS Simulator. Progressive disclosure of tool responses to reduce context usage. Use --mini param for build-only with tiny context footprint.
Configuration
View docs{
"mcpServers": {
"conorluddy-xc-mcp": {
"command": "npx",
"args": [
"-y",
"xc-mcp"
],
"env": {
"XC_MCP_DEFER_LOADING": "true",
"XCODE_CLI_MCP_TIMEOUT": "300 (default)",
"XCODE_CLI_MCP_CACHE_DIR": "path/to/cache",
"XCODE_CLI_MCP_LOG_LEVEL": "info"
}
}
}
}XC-MCP is a production-grade MCP server designed to automate Xcode and iOS workflows for AI agents. It delivers intelligent context management, progressive disclosure, and accessibility-first automation so you can control simulators, build pipelines, and UI interactions with minimal token overhead and high reliability.
You connect to the XC-MCP server from your MCP client and start issuing build, simulator, and UI automation commands just like you would with other MCP endpoints. Use progressive disclosure to retrieve concise summaries first, then fetch full details only when you need them. Prefer accessibility-first interactions whenever possible to minimize latency and token cost. If your client supports on-demand tool loading, enable it to take full advantage of deferred loading.
Key usage patterns you’ll implement regularly include: starting a build and obtaining a buildId for progressive logs, listing and inspecting simulators with on-demand details, managing apps on devices or simulators, and performing high-level UI actions that combine element discovery with tapping or typing. When you need detailed guidance for a specific tool, browse tool categories and retrieve full tool docs on demand, then execute with the exact parameters shown in the docs.
Prerequisites: you need macOS with Xcode command-line tools, and Node.js 18 or newer. Xcode 15+ is recommended for best compatibility.
Install XC-MCP globally so you can run it from anywhere, or run it without installation if you prefer. Then start the server using the provided MCP command.
Step-by-step commands you will run:
Configure your MCP client to connect to XC-MCP. The standard, built-in approach is to use a local stdio server configuration that runs via npx.
Environment variables can tune timeouts, log levels, and caching behavior. The following variables are commonly useful:
Leverage the two high-level workflow tools to simplify common sequences. Use workflow-tap-element to combine accessibility checks, element discovery, and tapping into a single operation. Use workflow-fresh-install when you need a complete app refresh cycle (shutdown, erase, boot, build, install, launch).
Keep your sessions efficient by enabling platform defer_loading so tools load on demand. In debugging scenarios, you can temporarily disable defer_loading to load all 29 tools at startup.
Progressive disclosure returns compact summaries first and provides cache IDs to fetch full details only if needed. This reduces token usage dramatically while preserving access to full information on demand.
When you need comprehensive tool documentation, use on-demand discovery commands to fetch the relevant docs for a specific tool and then execute with the exact parameters shown.
The server exposes a wide set of capabilities for Xcode builds, simulator control, UI automation, and handy utilities. Use the consolidated routers for common operations (for example, simctl-device for simulator lifecycle and idb-app for app operations). Each tool supports progressive disclosure to minimize upfront token usage.
Simulator lifecycle operations: boot, shutdown, create, delete, erase, clone, rename with auto-UDID and performance tracking
Manage apps on simulators: install, uninstall, launch, terminate with bundle ID resolution and launch arguments
IDB app operations for install, uninstall, launch, terminate across devices and simulators
Cache management with get-stats, get-config, set-config, clear across multiple layers
Persistence controls to enable/disable a cache and check status
Target management including list, describe, connect, and disconnect for devices and simulators
Progressive-disclosure build endpoint returning a buildId and a concise summary
Run tests with filtering and test plans, with cache-backed summaries
Clean build artifacts before or after builds to maintain clean state
List targets and schemes with smart caching to speed discovery
Retrieve Xcode and SDK versions for the environment
Fetch detailed logs and artifacts for a given buildId
Query the accessibility tree with all or point operations to understand UI structure
Tap on a screen using coordinates derived from semantic element discovery
Input text and control the keyboard during interactions
Perform gestures like swipes and pinches with coordinate transformations
Find elements semantically by label or identifier for precise interactions
Rapid assessment of screen accessibility quality to decide between accessibility tree or screenshot flows
Screenshots and video recordings with semantically meaningful naming
Vision-optimized base64 screenshots for UI verification
On-demand comprehensive tool documentation and examples
High-level abstraction that performs quality check, element find, and tap in one call
End-to-end clean install workflow: shutdown, erase, boot, build, install, launch