Expo Dev Build MCP Server

An MCP server that lets Claude see and interact with iOS devices running Expo development builds. Take screenshots, view logs, launch apps, and debug your mobile app through conversation.

What It Does

┌─────────────────┐                    ┌─────────────────┐                    ┌─────────────────┐
│  Claude Code    │ ◄── MCP Protocol ──►  This Server    │ ◄── USB/Tunnel ──► │  Your iPhone    │
│  or Desktop     │                    │  (Python)       │                    │  (Expo App)     │
└─────────────────┘                    └─────────────────┘                    └─────────────────┘

Available Tools:

• screenshot - Capture the device screen (Claude can see and analyze it)
• get_logs - Stream system logs for debugging
• list_apps - See installed applications
• launch_app - Start an app by bundle ID
• kill_app - Force quit an app
• device_info - Get model, iOS version, battery, etc.
• list_devices - Find connected iOS devices

Quick Start

1. Prerequisites

Requirement	How to Check
macOS	Required (iOS tools only work on Mac)
Python 3.10+	python3 --version (install via brew install python@3.12 if needed)
Homebrew	brew --version (install from https://brew.sh if needed)
iOS device	Physical iPhone/iPad connected via USB

2. Clone and Install

git clone https://github.com/ryan-crabbe/expo-dev-build-mcp.git
cd expo-dev-build-mcp

# Create virtual environment with Python 3.10+
python3 -m venv .venv
source .venv/bin/activate

# Upgrade pip and install
pip install --upgrade pip
pip install -e .

3. Prepare Your iOS Device

Connect and trust:

1. Connect your iPhone/iPad via USB cable
2. If prompted on the device, tap "Trust This Computer"
3. Verify connection: python3 -m pymobiledevice3 usbmux list

Enable Developer Mode (iOS 16+):

1. Open Xcode on your Mac and connect your device (this registers it as a developer device)
2. On your iPhone: Settings → Privacy & Security → Developer Mode → Enable
3. Restart when prompted

4. Start the Tunnel Daemon (iOS 17+ Required)

iOS 17+ requires a tunnel daemon for developer commands. Run this in a separate terminal and keep it running:

cd expo-dev-build-mcp
source .venv/bin/activate
sudo python3 -m pymobiledevice3 remote tunneld

Enter your Mac password when prompted. You'll see connection logs when it's working.

Tip: Keep this terminal open while using the MCP server. You can also set this up as a launchd service for automatic startup.

5. Test It Works

In a new terminal:

cd expo-dev-build-mcp
source .venv/bin/activate

# List devices
python3 -m pymobiledevice3 usbmux list

# Take a test screenshot
python3 -m pymobiledevice3 developer dvt screenshot test.png
open test.png

If the screenshot opens, you're ready to configure Claude.

6. Configure Claude

For Claude Code, add to your MCP settings (run claude mcp to find config location):

{
  "mcpServers": {
    "expo-dev": {
      "command": "/ABSOLUTE/PATH/TO/expo-dev-build-mcp/.venv/bin/python",
      "args": ["-m", "expo_dev_mcp.server"]
    }
  }
}

For Claude Desktop, add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "expo-dev": {
      "command": "/ABSOLUTE/PATH/TO/expo-dev-build-mcp/.venv/bin/python",
      "args": ["-m", "expo_dev_mcp.server"]
    }
  }
}

Important: Replace /ABSOLUTE/PATH/TO/ with the actual path. Find it with pwd in the project directory.

Restart Claude Code/Desktop after updating the config.

Usage

Once configured, ask Claude things like:

• "Take a screenshot of my phone"
• "What's on my iPhone screen?"
• "Show me the device logs"
• "What apps are installed?"
• "Launch com.mycompany.myexpoapp"
• "Kill the app and relaunch it"

Claude will use the MCP tools automatically and can see/analyze the screenshots.

Troubleshooting

"No device found"

• Check USB connection
• Run python3 -m pymobiledevice3 usbmux list - device should appear
• If not listed, try a different USB cable or port
• Make sure you tapped "Trust" on the device

"InvalidServiceError" or "Unable to connect to Tunneld"

• iOS 17+ requires the tunnel daemon running
• Start it in a separate terminal: sudo python3 -m pymobiledevice3 remote tunneld
• Keep that terminal open while using the MCP server

"Failed to take screenshot"

• Ensure Developer Mode is enabled (Settings → Privacy & Security → Developer Mode)
• Make sure tunneld is running (for iOS 17+)
• Try: python3 -m pymobiledevice3 developer dvt screenshot test.png

Screenshot works manually but not via MCP

• Check the path in your Claude config is correct (must be absolute path)
• Restart Claude Code/Desktop after config changes
• Check MCP server is loaded: run claude mcp in Claude Code

"sudo: a password is required"

• The tunneld command needs sudo for network permissions
• Run it in a regular terminal (not via script) so you can enter your password

How It Works

This server uses pymobiledevice3, a Python library that implements Apple's proprietary protocols for communicating with iOS devices:

• usbmuxd - USB multiplexing (multiple services over one USB connection)
• Lockdown - Device pairing and service discovery
• DVT (Developer Tools) - Screenshots, process control, instrumentation

No jailbreak required. It uses the same protocols as Xcode.

Project Structure

expo-dev-build-mcp/
├── pyproject.toml           # Package configuration
├── README.md                # This file
└── src/
    └── expo_dev_mcp/
        ├── __init__.py
        └── server.py        # MCP server implementation

Development

# Install in development mode
pip install -e .

# Run server directly (for testing)
python -m expo_dev_mcp.server

# Test with MCP Inspector
npx @modelcontextprotocol/inspector python -m expo_dev_mcp.server

Future: Gesture Support

This is currently view-only. Adding tap/swipe gestures would require WebDriverAgent, which needs:

• Apple Developer account (paid)
• Code signing and provisioning profiles
• WebDriverAgent installed on device

License

MIT