XC-MCP Server
- typescript
49
GitHub Stars
typescript
Language
6 months ago
First Indexed
2 months ago
Catalog Refreshed
Documentation & install
Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.
Installation
Add the following to your MCP client configuration file.
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.
How to use
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.
How to install
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:
Configuration and environment
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:
Workflow features and best practices
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.
Notes on progressive disclosure and RTFM usage
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.
Build and interact with the API
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.
Available tools
simctl-device
Simulator lifecycle operations: boot, shutdown, create, delete, erase, clone, rename with auto-UDID and performance tracking
simctl-app
Manage apps on simulators: install, uninstall, launch, terminate with bundle ID resolution and launch arguments
idb-app
IDB app operations for install, uninstall, launch, terminate across devices and simulators
cache
Cache management with get-stats, get-config, set-config, clear across multiple layers
persistence
Persistence controls to enable/disable a cache and check status
idb-targets
Target management including list, describe, connect, and disconnect for devices and simulators
xcodebuild-build
Progressive-disclosure build endpoint returning a buildId and a concise summary
xcodebuild-test
Run tests with filtering and test plans, with cache-backed summaries
xcodebuild-clean
Clean build artifacts before or after builds to maintain clean state
xcodebuild-list
List targets and schemes with smart caching to speed discovery
xcodebuild-version
Retrieve Xcode and SDK versions for the environment
xcodebuild-get-details
Fetch detailed logs and artifacts for a given buildId
idb-ui-describe
Query the accessibility tree with all or point operations to understand UI structure
idb-ui-tap
Tap on a screen using coordinates derived from semantic element discovery
idb-ui-input
Input text and control the keyboard during interactions
idb-ui-gesture
Perform gestures like swipes and pinches with coordinate transformations
idb-ui-find-element
Find elements semantically by label or identifier for precise interactions
accessibility-quality-check
Rapid assessment of screen accessibility quality to decide between accessibility tree or screenshot flows
simctl-io
Screenshots and video recordings with semantically meaningful naming
screenshot
Vision-optimized base64 screenshots for UI verification
rtfm
On-demand comprehensive tool documentation and examples
workflow-tap-element
High-level abstraction that performs quality check, element find, and tap in one call
workflow-fresh-install
End-to-end clean install workflow: shutdown, erase, boot, build, install, launch
