# iOS Development MCP Server
A comprehensive Model Context Protocol (MCP) server providing iOS simulator control and Swift/Xcode development tools.
## Status
**Current Version:** 0.4.0 (Active Development)
### Implemented Features
✅ **Core Infrastructure**
- Command execution wrapper with timeout management
- Structured error handling system
- Device resolution and state management
- Type-safe tool definitions
✅ **Simulator Device Management** (4 tools)
- `simulator_list_devices` - List all available iOS simulators
- `simulator_boot` - Boot a simulator device
- `simulator_shutdown` - Shutdown a running simulator
- `simulator_get_info` - Get detailed device information
✅ **Simulator UI Interaction** (4 tools)
- `simulator_screenshot` - Capture and compress screenshots (JPEG, 80% quality)
- `simulator_tap` - Tap at specific coordinates
- `simulator_swipe` - Swipe gestures with direction detection
- `simulator_long_press` - Long press for context menus
✅ **Simulator App Management** (6 tools)
- `simulator_launch_app` - Launch apps by bundle identifier
- `simulator_terminate_app` - Force quit running apps
- `simulator_install_app` - Install .app bundles
- `simulator_uninstall_app` - Remove apps and their data
- `simulator_open_url` - Open URLs and deep links
- `simulator_get_logs` - Retrieve filtered log entries
✅ **Simulator Input Simulation** (3 tools)
- `simulator_type_text` - Type text into focused text fields
- `simulator_press_home` - Press home button
- `simulator_send_keys` - Send hardware keyboard shortcuts
### In Progress
🚧 **Simulator Environment Tools** (7 tools planned)
- Location simulation
- Appearance settings
- Push notifications
### Planned Features
📋 **Simulator Tools** (20+ additional tools)
- App lifecycle management
- Input simulation
- Environment configuration
- UI debugging
- Performance monitoring
📋 **Build Tools** (7 tools)
- xcodebuild wrapper
- Build and run workflows
- Scheme management
📋 **Test Tools** (6 tools)
- Unit and UI test execution
- Coverage generation
- Result parsing
📋 **Project Tools** (9 tools)
- Xcode project management
- File operations
- Configuration management
📋 **SPM Tools** (7 tools)
- Package dependency management
## Installation
### Prerequisites
- **macOS** (iOS Simulator only available on macOS)
- **Xcode** 15+ with Command Line Tools
- **Node.js** 18+
### Setup
```bash
# Clone or navigate to project directory
cd ios-dev-mcp-server
# Install dependencies
npm install
# Build
npm run build
```
## Usage
### Claude Code Integration (Recommended) 🚀
**Quick Install:**
```bash
./install-claude-code.sh
```
This automated script will:
- ✅ Check all prerequisites
- ✅ Build the project
- ✅ Configure Claude Code settings
- ✅ Provide next steps
**Manual Setup:**
See [CLAUDE_CODE_SETUP.md](./CLAUDE_CODE_SETUP.md) for detailed instructions.
**Testing in Claude Code:**
After installation, try these prompts:
- "List all available iOS simulators"
- "Boot an iPhone 15 Pro simulator"
- "Get info about the booted simulator"
- "Take a screenshot of the booted simulator"
- "Tap at coordinates 200, 400 on the simulator"
- "Install my app at ./build/MyApp.app and launch it"
- "Get the last 100 logs from the simulator"
- "Open https://apple.com on the simulator"
### Claude Desktop Integration
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"ios-dev": {
"command": "node",
"args": ["/path/to/ios-dev-mcp-server/build/index.js"]
}
}
}
```
### MCP Inspector (for testing)
```bash
npm run inspector
```
Opens web UI at http://localhost:6274 for interactive tool testing.
## Available Tools
### Simulator Device Management
#### simulator_list_devices
List all available iOS simulator devices with their current states.
**Parameters:** None
**Example Response:**
```json
{
"summary": "Found 5 device(s) (1 booted)",
"devices": [
{
"udid": "ABC-123-DEF",
"name": "iPhone 15 Pro",
"state": "Booted",
"runtime": "iOS 17.2",
"deviceType": "iPhone15,2"
}
]
}
```
#### simulator_boot
Boot an iOS simulator device by UDID.
**Parameters:**
- `device` (string, required): Device UDID to boot
#### simulator_shutdown
Shutdown a running iOS simulator device.
**Parameters:**
- `device` (string, required): Device UDID to shutdown
#### simulator_get_info
Get detailed information about a specific simulator device.
**Parameters:**
- `device` (string, optional): Device UDID or "booted" (default: "booted")
### Simulator UI Interaction
#### simulator_screenshot
Capture a screenshot from the iOS simulator with automatic compression.
**Parameters:**
- `device` (string, optional): Device UDID or "booted" (default: "booted")
- `quality` (number, optional): JPEG quality 1-100 (default: 80)
- `maxWidth` (number, optional): Maximum width in pixels (default: 800)
- `maxHeight` (number, optional): Maximum height in pixels (default: 1400)
**Returns:**
- Base64-encoded JPEG image
- Compression metadata (original size, compressed size, ratio)
**Example:**
```
Take a screenshot of the simulator
```
#### simulator_tap
Tap at specific x,y coordinates on the simulator screen.
**Parameters:**
- `device` (string, optional): Device UDID or "booted"
- `x` (number, required): X coordinate in pixels
- `y` (number, required): Y coordinate in pixels
**Example:**
```
Tap at coordinates 200, 400 on the simulator
```
#### simulator_swipe
Perform a swipe gesture from one point to another.
**Parameters:**
- `device` (string, optional): Device UDID or "booted"
- `x1` (number, required): Start X coordinate
- `y1` (number, required): Start Y coordinate
- `x2` (number, required): End X coordinate
- `y2` (number, required): End Y coordinate
- `duration` (number, optional): Swipe duration in seconds (default: 0.3)
**Returns:**
- Swipe direction (left, right, up, down)
- Distance in pixels
**Example:**
```
Swipe from 200,800 to 200,200 on the simulator
```
#### simulator_long_press
Perform a long press (tap and hold) at specific coordinates.
**Parameters:**
- `device` (string, optional): Device UDID or "booted"
- `x` (number, required): X coordinate in pixels
- `y` (number, required): Y coordinate in pixels
- `duration` (number, optional): Press duration in seconds (default: 1.0)
**Example:**
```
Long press at coordinates 300, 500 for 2 seconds
```
### Simulator App Management
#### simulator_launch_app
Launch an iOS app on the simulator by its bundle identifier.
**Parameters:**
- `device` (string, optional): Device UDID or "booted" (default: "booted")
- `bundleId` (string, required): App bundle identifier (e.g., "com.apple.mobilesafari")
**Returns:**
- Process ID (PID) if available
- Success confirmation
**Example:**
```
Launch com.mycompany.myapp on the simulator
```
#### simulator_terminate_app
Force quit a running app on the simulator.
**Parameters:**
- `device` (string, optional): Device UDID or "booted"
- `bundleId` (string, required): App bundle identifier to terminate
**Example:**
```
Terminate com.apple.mobilesafari
```
#### simulator_install_app
Install an iOS app (.app bundle) on the simulator.
**Parameters:**
- `device` (string, optional): Device UDID or "booted"
- `appPath` (string, required): Path to .app bundle (absolute or relative)
**Returns:**
- Installation confirmation
- Resolved app path
**Example:**
```
Install the app at ./build/Debug-iphonesimulator/MyApp.app
```
#### simulator_uninstall_app
Uninstall an app from the simulator, removing the app and all its data.
**Parameters:**
- `device` (string, optional): Device UDID or "booted"
- `bundleId` (string, required): App bundle identifier to uninstall
**Example:**
```
Uninstall com.mycompany.myapp from the simulator
```
#### simulator_open_url
Open a URL on the simulator. Supports web URLs (Safari), deep links, and universal links.
**Parameters:**
- `device` (string, optional): Device UDID or "booted"
- `url` (string, required): URL to open (http://, https://, or custom scheme)
**Example:**
```
Open https://apple.com on the simulator
Open myapp://settings/profile on the simulator
```
#### simulator_get_logs
Retrieve recent log entries from the simulator with optional filtering.
**Parameters:**
- `device` (string, optional): Device UDID or "booted"
- `predicate` (string, optional): Log predicate filter (e.g., `processImagePath CONTAINS "MyApp"`)
- `lines` (number, optional): Number of recent lines to return (default: 100)
- `level` (string, optional): Minimum log level ("debug", "info", "default", "error", "fault")
**Returns:**
- Filtered log entries
- Total and returned line counts
- Applied filters
**Example:**
```
Get logs for MyApp with errors only
Get the last 50 log lines from the simulator
```
### Simulator Input Simulation
#### simulator_type_text
Type text into the currently focused text field on the simulator.
**Parameters:**
- `device` (string, optional): Device UDID or "booted" (default: "booted")
- `text` (string, required): Text to type into the focused text field
**Returns:**
- Number of characters typed
- Success confirmation
**Requirements:**
- A text field must be active (keyboard visible) before typing
**Example:**
```
Type "Hello World" into the simulator
Type "test@example.com" into the email field
```
#### simulator_press_home
Press the home button to return to the home screen.
**Parameters:**
- `device` (string, optional): Device UDID or "booted" (default: "booted")
**Returns:**
- Success confirmation
**Example:**
```
Press the home button on the simulator
Go to the home screen
```
#### simulator_send_keys
Send hardware keyboard input and shortcuts to the simulator.
**Parameters:**
- `device` (string, optional): Device UDID or "booted" (default: "booted")
- `text` (string, required): Key or shortcut to send
**Supported Shortcuts:**
- `cmd-h` or `home` - Home button
- `cmd-l` or `lock` - Lock screen
- `cmd-shift-h` or `app-switcher` - App switcher
- `siri` - Activate Siri
**Returns:**
- Action performed
- Success confirmation
**Example:**
```
Send cmd-h to go home
Send lock to lock the screen
Send siri to activate Siri
```
## Development
### Project Structure
```
ios-dev-mcp-server/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── shared/ # Core infrastructure
│ │ ├── executor.ts # Command execution wrapper
│ │ ├── simulator.ts # Device management helpers
│ │ ├── types.ts # TypeScript interfaces
│ │ └── errors.ts # Error handling system
│ ├── tools/ # Tool implementations
│ │ └── simulator/ # Simulator tools
│ │ ├── device.ts # Device management
│ │ └── index.ts # Tool registration
│ └── schemas/ # Zod validation schemas
│ └── simulator.ts # Simulator tool schemas
├── tests/ # Test suite
└── build/ # Compiled output
```
### Scripts
```bash
npm run build # Compile TypeScript
npm run dev # Watch mode
npm test # Run tests
npm run test:unit # Unit tests only
npm run test:coverage # Coverage report
npm run inspector # Launch MCP Inspector
```
### Adding New Tools
1. Define Zod schema in `src/schemas/[module].ts`
2. Implement tool in `src/tools/[module]/[feature].ts`
3. Export tool in module's `index.ts`
4. Register in `src/index.ts`
Example:
```typescript
import { z } from 'zod';
import type { ToolDefinition } from '../../shared/types.js';
const MyToolSchema = z.object({
param: z.string().describe('Parameter description')
});
export const myTool: ToolDefinition<typeof MyToolSchema> = {
name: 'tool_name',
description: 'What this tool does',
inputSchema: {
type: 'object',
properties: {
param: { type: 'string', description: 'Parameter description' }
},
required: ['param']
},
schema: MyToolSchema,
handler: async (args) => {
// Implementation
return {
content: [{ type: 'text', text: 'Result' }]
};
}
};
```
## Architecture
### Key Design Patterns
**Tool Registry Pattern:**
- Central Map<string, ToolDefinition> in main server
- Module registration functions add tools to registry
- Request dispatcher routes to appropriate handler
**Device Resolution:**
- "booted" → first booted device UDID
- Validates device existence before operations
- Clear error messages with available devices list
**Error Handling:**
- MCPToolError base class with .toToolResult()
- Structured errors: code, message, details, recovery
- Domain-specific error types (SimulatorError, BuildError, etc.)
**Command Execution:**
- Centralized executor with timeout management
- Convenience wrappers: simctl(), xcodebuild(), swiftPackage()
- Structured CommandResult with stdout, stderr, exitCode
## Claude Code Plugin Marketplace
This plugin is designed to be published to the Claude Code Plugin Marketplace.
### For Plugin Users
**Once published, install with:**
```bash
# Install from marketplace (coming soon)
claude plugin install ios-dev
```
Or search in Claude Code:
Settings > Plugins > Browse Marketplace > "iOS Development Tools"
### For Plugin Developers
Want to publish to the marketplace?
1. **Review:** [MARKETPLACE_PUBLISHING.md](./MARKETPLACE_PUBLISHING.md)
2. **Create Assets:** See [assets/ASSETS.md](./assets/ASSETS.md)
3. **Package:** `npm run package`
4. **Publish:** Follow marketplace submission guide
**Pre-publication checklist:**
- [ ] All tools tested and working
- [ ] Assets created (icon.png, screenshots)
- [ ] Documentation complete
- [ ] GitHub repository created
- [ ] Version tagged
## Project Status
**Current:** v0.4.0 - Development/Pre-release
**Status:** Complete basic simulator interaction, assets needed for marketplace
**What's Working:**
- ✅ 17 simulator tools (device, UI, app, input)
- ✅ 4 device management tools (list, boot, shutdown, info)
- ✅ 4 UI interaction tools (screenshot, tap, swipe, long press)
- ✅ 6 app management tools (launch, terminate, install, uninstall, open URL, logs)
- ✅ 3 input simulation tools (type text, press home, send keys)
- ✅ MCP server infrastructure
- ✅ Type-safe operations with Zod validation
- ✅ Comprehensive error handling with recovery suggestions
- ✅ Screenshot compression (<200KB)
- ✅ Local installation via script
**Before Marketplace:**
- ⏳ Create plugin icon (512x512)
- ⏳ Create screenshots
- ⏳ Public GitHub repository
- ⏳ Marketplace submission
## License
MIT
## Contributing
This project is currently in active development. Tool implementations follow the established patterns in the shared infrastructure and existing modules.
