xcode-mcp
MCP server for Xcode developer tools.
Installation
npm install
npm run build
Usage
Claude Desktop Configuration
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"xcode": {
"command": "node",
"args": ["/Users/YOUR_USERNAME/Projects/xcode-mcp/dist/index.js"]
}
}
}
Available Tools
iOS Simulator (simctl)
Control iOS Simulators via xcrun simctl.
| Tool | Description |
|---|---|
simctl_list | List available simulators, device types, runtimes, or device pairs |
simctl_boot | Boot a simulator device |
simctl_shutdown | Shutdown a simulator device or all simulators |
simctl_install | Install an app bundle on a simulator |
simctl_launch | Launch an app on a simulator |
simctl_terminate | Terminate a running app without shutting down the simulator |
simctl_uninstall | Uninstall an app from a simulator |
simctl_openurl | Open a URL or deep link on a simulator |
simctl_push | Send a push notification to an app |
simctl_location | Set or clear the simulated GPS location |
simctl_privacy | Grant, revoke, or reset privacy permissions for an app |
simctl_io_screenshot | Capture a screenshot from a simulator |
Device Identification
All simulator tools that require a device accept:
- Device UDID (e.g.,
"3A8C9B5F-1234-5678-9ABC-DEF012345678") - Device name (e.g.,
"iPhone 16 Pro") - Special value
"booted"for the currently booted simulator
Examples
List all devices:
{"name": "simctl_list", "arguments": {"filter": "devices"}}
Boot a simulator:
{"name": "simctl_boot", "arguments": {"device": "iPhone 16 Pro"}}
Take a screenshot:
{"name": "simctl_io_screenshot", "arguments": {"device": "booted"}}
Send a push notification:
{
"name": "simctl_push",
"arguments": {
"device": "booted",
"bundle_id": "com.example.app",
"payload": {
"aps": {
"alert": {
"title": "Test",
"body": "Hello from MCP!"
}
}
}
}
}
Set location:
{
"name": "simctl_location",
"arguments": {
"device": "booted",
"action": "set",
"latitude": 37.7749,
"longitude": -122.4194
}
}
Grant camera permission:
{
"name": "simctl_privacy",
"arguments": {
"device": "booted",
"action": "grant",
"service": "camera",
"bundle_id": "com.example.app"
}
}
WebDriverAgent (wda)
UI automation for iOS Simulator apps via WebDriverAgent. Enables tapping, swiping, typing, and finding UI elements.
| Tool | Description |
|---|---|
wda_status | Check WebDriverAgent server connectivity |
wda_tap | Tap at coordinates, by accessibility ID, or element ID |
wda_type | Type text into the currently focused text field |
wda_swipe | Perform a swipe gesture from start to end coordinates |
wda_find | Find UI elements by accessibility ID, class name, or predicate |
wda_source | Get the UI hierarchy (accessibility tree) as XML |
wda_home | Press the home button |
wda_alert | Accept or dismiss system alerts |
Prerequisites
-
Clone WebDriverAgent (one-time):
git clone https://github.com/appium/WebDriverAgent.git cd WebDriverAgent -
Start WDA on a simulator (keep running in a terminal):
xcodebuild test -project WebDriverAgent.xcodeproj \ -scheme WebDriverAgentRunner \ -destination 'platform=iOS Simulator,name=iPhone 16 Pro' -
Verify WDA is running:
curl http://localhost:8100/status
Coordinate System
All coordinates are in points (logical pixels), not physical pixels. Use wda_source to see element positions in the UI hierarchy XML.
Common Parameters
All WDA tools accept these optional parameters:
bundle_id: Activate a specific app before the actionport: WDA server port (default: 8100)
Examples
Check WDA status:
{"name": "wda_status", "arguments": {}}
Tap at coordinates:
{"name": "wda_tap", "arguments": {"x": 200, "y": 400}}
Tap by accessibility ID:
{"name": "wda_tap", "arguments": {"accessibility_id": "login_button"}}
Tap with app activation:
{"name": "wda_tap", "arguments": {"accessibility_id": "login", "bundle_id": "com.example.app"}}
Type text:
{"name": "wda_type", "arguments": {"text": "hello@example.com"}}
Swipe down (scroll up):
{
"name": "wda_swipe",
"arguments": {
"start_x": 200,
"start_y": 400,
"end_x": 200,
"end_y": 200,
"duration": 500
}
}
Find elements:
{"name": "wda_find", "arguments": {"strategy": "accessibility id", "value": "submit_button"}}
Get UI hierarchy:
{"name": "wda_source", "arguments": {}}
Handle alert:
{"name": "wda_alert", "arguments": {"action": "accept"}}
Xcode Build (xcodebuild)
Build, test, and manage Xcode projects via xcodebuild.
| Tool | Description |
|---|---|
xcodebuild_list | List schemes, targets, and configurations for a project or workspace |
xcodebuild_build | Build a scheme for a destination with structured result parsing |
xcodebuild_test | Run tests and return structured results with pass/fail counts |
xcodebuild_clean | Clean build artifacts for a scheme |
xcodebuild_show_build_settings | Show build configuration settings |
Project Auto-Detection
All xcodebuild tools can automatically detect the project or workspace in the current directory. They prefer .xcworkspace over .xcodeproj. You can also specify explicit paths:
workspace: Path to a.xcworkspacefileproject: Path to a.xcodeprojfiledirectory: Directory to search for projects (defaults to cwd)
Destination Handling
The destination parameter accepts:
- Device names (e.g.,
"iPhone 16 Pro") - automatically resolved to simulator UDID - Full destination strings (e.g.,
"platform=iOS Simulator,name=iPhone 16 Pro")
Examples
List schemes:
{"name": "xcodebuild_list", "arguments": {}}
Build a scheme:
{
"name": "xcodebuild_build",
"arguments": {
"scheme": "MyApp",
"destination": "iPhone 16 Pro",
"configuration": "Debug"
}
}
Run tests:
{
"name": "xcodebuild_test",
"arguments": {
"scheme": "MyApp",
"destination": "iPhone 16 Pro",
"only_testing": ["MyAppTests/testLogin"]
}
}
Clean build:
{
"name": "xcodebuild_clean",
"arguments": {
"scheme": "MyApp"
}
}
Show build settings:
{
"name": "xcodebuild_show_build_settings",
"arguments": {
"scheme": "MyApp",
"configuration": "Release"
}
}
Development
# Run in development mode
npm run dev
# Build
npm run build
# Test
npm test
License
MIT