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

Usage

Claude Code Integration (Recommended) 🚀

Quick Install:

This automated script will:

• ✅ Check all prerequisites

• ✅ Build the project

• ✅ Configure Claude Code settings

• ✅ Provide next steps

Manual Setup:

See 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):

MCP Inspector (for testing)

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

Development

Project Structure

Scripts

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:

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:

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

2. Create Assets: See 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.