# xcode-mcp
MCP server for Xcode developer tools.
## Installation
```bash
npm install
npm run build
```
## Usage
### Claude Desktop Configuration
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```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:**
```json
{"name": "simctl_list", "arguments": {"filter": "devices"}}
```
**Boot a simulator:**
```json
{"name": "simctl_boot", "arguments": {"device": "iPhone 16 Pro"}}
```
**Take a screenshot:**
```json
{"name": "simctl_io_screenshot", "arguments": {"device": "booted"}}
```
**Send a push notification:**
```json
{
"name": "simctl_push",
"arguments": {
"device": "booted",
"bundle_id": "com.example.app",
"payload": {
"aps": {
"alert": {
"title": "Test",
"body": "Hello from MCP!"
}
}
}
}
}
```
**Set location:**
```json
{
"name": "simctl_location",
"arguments": {
"device": "booted",
"action": "set",
"latitude": 37.7749,
"longitude": -122.4194
}
}
```
**Grant camera permission:**
```json
{
"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
1. **Clone WebDriverAgent** (one-time):
```bash
git clone https://github.com/appium/WebDriverAgent.git
cd WebDriverAgent
```
2. **Start WDA on a simulator** (keep running in a terminal):
```bash
xcodebuild test -project WebDriverAgent.xcodeproj \
-scheme WebDriverAgentRunner \
-destination 'platform=iOS Simulator,name=iPhone 16 Pro'
```
3. **Verify WDA is running**:
```bash
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 action
- `port`: WDA server port (default: 8100)
#### Examples
**Check WDA status:**
```json
{"name": "wda_status", "arguments": {}}
```
**Tap at coordinates:**
```json
{"name": "wda_tap", "arguments": {"x": 200, "y": 400}}
```
**Tap by accessibility ID:**
```json
{"name": "wda_tap", "arguments": {"accessibility_id": "login_button"}}
```
**Tap with app activation:**
```json
{"name": "wda_tap", "arguments": {"accessibility_id": "login", "bundle_id": "com.example.app"}}
```
**Type text:**
```json
{"name": "wda_type", "arguments": {"text": "hello@example.com"}}
```
**Swipe down (scroll up):**
```json
{
"name": "wda_swipe",
"arguments": {
"start_x": 200,
"start_y": 400,
"end_x": 200,
"end_y": 200,
"duration": 500
}
}
```
**Find elements:**
```json
{"name": "wda_find", "arguments": {"strategy": "accessibility id", "value": "submit_button"}}
```
**Get UI hierarchy:**
```json
{"name": "wda_source", "arguments": {}}
```
**Handle alert:**
```json
{"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 `.xcworkspace` file
- `project`: Path to a `.xcodeproj` file
- `directory`: 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:**
```json
{"name": "xcodebuild_list", "arguments": {}}
```
**Build a scheme:**
```json
{
"name": "xcodebuild_build",
"arguments": {
"scheme": "MyApp",
"destination": "iPhone 16 Pro",
"configuration": "Debug"
}
}
```
**Run tests:**
```json
{
"name": "xcodebuild_test",
"arguments": {
"scheme": "MyApp",
"destination": "iPhone 16 Pro",
"only_testing": ["MyAppTests/testLogin"]
}
}
```
**Clean build:**
```json
{
"name": "xcodebuild_clean",
"arguments": {
"scheme": "MyApp"
}
}
```
**Show build settings:**
```json
{
"name": "xcodebuild_show_build_settings",
"arguments": {
"scheme": "MyApp",
"configuration": "Release"
}
}
```
## Development
```bash
# Run in development mode
npm run dev
# Build
npm run build
# Test
npm test
```
## License
MIT
