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

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

2. Clone and Install

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:

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:

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

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

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.

Remote Access (via ngrok)

The HTTP/ngrok mode lets you access an iPhone from a different machine than where it's physically connected.

When to use this:

When you DON'T need this:

If your iPhone and Mac are always together (typical solo dev setup), just use the default stdio mode - it's simpler and faster.

Quick Start (Recommended)

This starts both the server and ngrok, then prints the Claude configuration.

Manual Setup

Terminal 1: Start tunneld (iOS 17+)

Terminal 2: Start MCP server in HTTP mode

Note the auth token printed to the console.

Terminal 3: Start ngrok

Note the ngrok URL (e.g., https://abc123.ngrok.io).

Configure Claude for Remote Access

Security

• Random auth token - Generated on each server start

• HTTPS - ngrok provides TLS encryption

• Short-lived - Tunnel only exists while server runs

• Random URL - ngrok URLs are hard to guess

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

Development

Future: Gesture Support (Phase 2)

This MVP is view-only. Phase 2 would add tap/swipe gestures via WebDriverAgent, requiring:

• Apple Developer account (paid)

• Code signing and provisioning profiles

• WebDriverAgent installed on device

See the project research notes for implementation details.

License

MIT