The xcode-mcp server provides comprehensive programmatic control over Xcode development tools for iOS simulator management, UI automation, and build processes via Claude Desktop.
iOS Simulator Management (simctl):
List and discover simulators (devices, device types, runtimes, pairs) with optional search filtering
Boot and shutdown simulators (individual or all at once)
Install, launch, terminate, and uninstall apps with support for launch arguments and debugger attachment
Open URLs or deep links for testing app integrations
Send push notifications with custom payloads
Set or clear simulated GPS coordinates for location-based testing
Manage privacy permissions (grant, revoke, reset) for camera, microphone, location, contacts, photos, etc.
Capture screenshots in multiple formats (PNG, JPEG, TIFF) with optional masking
Accept device UDIDs, human-readable names (e.g., "iPhone 16 Pro"), or "booted" keyword for flexibility
UI Automation (wda via WebDriverAgent):
Check server connectivity
Perform tap gestures by coordinates, accessibility ID, or element ID
Type text into input fields
Execute swipe gestures
Find UI elements using various strategies
Retrieve complete UI hierarchy as XML
Simulate pressing the home button
Accept or dismiss system alerts
Xcode Build Management (xcodebuild):
List schemes, targets, and configurations for projects/workspaces
Build project schemes for specific destinations and configurations
Run tests with structured results
Clean build artifacts
Display build configuration settings
Key Use Cases: Automated testing workflows, UI/UX testing, screenshot generation, location-based feature testing, push notification verification, privacy permission testing, deep link validation, and CI/CD pipeline simulator management.
Provides comprehensive control over iOS simulator devices, enabling app installation and uninstallation, push notification testing, location simulation, and management of privacy permissions.
Integrates with Xcode's command-line tools (simctl) to manage the lifecycle of iOS simulators, including booting, shutting down, and capturing device screenshots.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@xcode-mcpTake a screenshot of the booted simulator"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
xcode-mcp
MCP server for Xcode developer tools.
Installation
npm install
npm run buildUsage
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 |
| List available simulators, device types, runtimes, or device pairs |
| Boot a simulator device |
| Shutdown a simulator device or all simulators |
| Install an app bundle on a simulator |
| Launch an app on a simulator |
| Terminate a running app without shutting down the simulator |
| Uninstall an app from a simulator |
| Open a URL or deep link on a simulator |
| Send a push notification to an app |
| Set or clear the simulated GPS location |
| Grant, revoke, or reset privacy permissions for an app |
| 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 |
| Check WebDriverAgent server connectivity |
| Tap at coordinates, by accessibility ID, or element ID |
| Type text into the currently focused text field |
| Perform a swipe gesture from start to end coordinates |
| Find UI elements by accessibility ID, class name, or predicate |
| Get the UI hierarchy (accessibility tree) as XML |
| Press the home button |
| Accept or dismiss system alerts |
Prerequisites
Clone WebDriverAgent (one-time):
git clone https://github.com/appium/WebDriverAgent.git cd WebDriverAgentStart 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 |
| List schemes, targets, and configurations for a project or workspace |
| Build a scheme for a destination with structured result parsing |
| Run tests and return structured results with pass/fail counts |
| Clean build artifacts for a scheme |
| 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 UDIDFull 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 testLicense
MIT
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.