An MCP (Model Context Protocol) server that provides tools to interact with the iOS Simulator. Take screenshots, inspect UI hierarchy, tap, swipe, type, set GPS location, and more.

Works with any MCP-compatible client, including Claude Code, Claude Desktop, and others.

# 1. Install prerequisites xcode-select --install brew tap facebook/fb brew install idb-companion uv pipx pipx ensurepath pipx install fb-idb --python python3.11 # 2. Clone and install the MCP git clone https://github.com/whitesmith/ios-simulator-mcp.git ~/ios-simulator-mcp cd ~/ios-simulator-mcp uv sync # 3. Add to Claude Code settings (see Configuration section below) claude mcp add ios-simulator \ -- uv run --directory ~/ios-simulator-mcp ios-simulator-mcp # 4. Restart Claude Code

This MCP uses two underlying tools:

xcode-select --install

IDB is required for UI interactions (tap, swipe, type, UI hierarchy). It has two components that must both be installed:

brew tap facebook/fb brew install idb-companion

The idb command comes from the fb-idb Python package. Install it globally with pipx:

# Install pipx if you don't have it brew install pipx pipx ensurepath # Install fb-idb globally (use Python 3.11 for compatibility) pipx install fb-idb --python python3.11

Note: The fb-idb package has compatibility issues with Python 3.14. Use Python 3.11 or 3.12.

# Check idb-companion which idb_companion # Should output: /opt/homebrew/bin/idb_companion # Check idb CLI which idb # Should output: ~/.local/bin/idb # Test connectivity idb list-targets # Should list all available simulators

brew install uv

Clone the repository and install dependencies:

git clone https://github.com/whitesmith/ios-simulator-mcp.git ~/ios-simulator-mcp cd ~/ios-simulator-mcp uv sync

The quickest way is using the CLI:

claude mcp add ios-simulator -- uv run --directory /Users/yourname/ios-simulator-mcp ios-simulator-mcp

Or manually add to ~/.claude/settings.json (global) or .mcp.json in your project root (project-specific):

{ "mcpServers": { "ios-simulator": { "command": "uv", "args": ["run", "--directory", "/Users/yourname/ios-simulator-mcp", "ios-simulator-mcp"] } } }

Replace /Users/yourname/ios-simulator-mcp with the absolute path where you cloned the repository.

Note: Use an absolute path (e.g., /Users/yourname/ios-simulator-mcp), not ~, since JSON values are not processed by a shell.

Then restart Claude Code or run /mcp to reload MCP servers.

Add to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json):

{ "mcpServers": { "ios-simulator": { "command": "uv", "args": ["run", "--directory", "/Users/yourname/ios-simulator-mcp", "ios-simulator-mcp"] } } }

Then restart Claude Desktop.

Once configured, your MCP client can use these tools automatically. Here are some examples with Claude Code:

Claude: Let me check how the new balance screen looks. [Uses screenshot tool] Claude: I can see the balance card is displaying correctly with the $50.00 amount. However, the "Add Funds" button appears to be cut off on the right edge. Let me fix the padding... 

Claude: I'll test the login flow. [Uses launch_app with bundle_id "com.example.myapp"] [Uses screenshot to see current state] [Uses get_ui_hierarchy to find the email field coordinates] [Uses tap_and_type to enter email] [Uses tap to press login button] [Uses wait for 2 seconds] [Uses screenshot to verify login succeeded] 

Claude: Let me test the pickup location feature in San Francisco. [Uses set_location with lat=37.7749, lng=-122.4194] [Uses screenshot to verify map updated] 

1. Check that the MCP is configured in ~/.claude/settings.json or .mcp.json
2. Restart Claude Code or run /mcp to reload servers
3. Check for errors in the MCP server startup

This is the most common issue. The fb-idb Python package must be installed globally, not just in the MCP's virtual environment:

# Install pipx if needed brew install pipx pipx ensurepath # Install fb-idb globally with Python 3.11 (3.14 has compatibility issues) pipx install fb-idb --python python3.11 # Verify which idb # Should show ~/.local/bin/idb

The MCP will auto-connect to a booted simulator. If none is booted, use:

boot_simulator with device_name="iPhone 15 Pro" 

Or boot one manually:

xcrun simctl boot "iPhone 16"

Restart the idb companion:

idb kill idb_companion --udid <simulator-udid>

Or connect manually:

idb connect <simulator-udid>

Make sure the simulator has an app open. The accessibility tree may be empty on the home screen or system dialogs.

Ensure the simulator is fully booted and visible. Test with:

xcrun simctl io booted screenshot /tmp/test.png

If you see errors like RuntimeError: There is no current event loop, you're likely using Python 3.14 which has asyncio changes incompatible with fb-idb. Reinstall with an older Python:

pipx uninstall fb-idb pipx install fb-idb --python python3.11

cd ~/ios-simulator-mcp uv sync uv run ios-simulator-mcp # runs the server directly (for testing)

When the MCP client calls a tool:

1. Simulator management (list_simulators, boot_simulator) uses xcrun simctl
2. Screenshots use xcrun simctl io <udid> screenshot
3. UI interactions (tap, swipe, type_text) use idb ui commands
4. UI hierarchy uses idb ui describe-all to get the accessibility tree
5. App management (launch_app, terminate_app) uses idb commands
6. Location uses xcrun simctl location

The MCP automatically connects to an already-booted simulator, or boots the latest iPhone if none is running.

• macOS only - iOS Simulator only runs on macOS
• Simulator only - Does not support physical iOS devices (idb does, but this MCP is configured for simulators)
• UI hierarchy on app screens - The accessibility tree may be empty or limited on the home screen, system dialogs, or apps without accessibility labels
• Coordinate-based interactions - Taps and swipes use absolute coordinates; you'll need to use get_ui_hierarchy to find element positions
• No gesture recording - Complex multi-touch gestures are not supported
• Screenshot size - Screenshots are compressed to JPEG and capped at ~2MB for efficient transmission

MIT