iPhone-mcp

MCP server that lets AI agents control real iPhones and iPhone simulators on MacOS. Works with Claude Code, Cursor, Codex, OpenCode, and any MCP-compatible AI agent.

Requirements

• macOS
• Xcode (install from App Store or xcode-select --install)
• Node.js 18+
• Homebrew

Installation

npm install @blitzdev/iphone-mcp

Quick Start

Global (use in any project)

npx @blitzdev/iphone-mcp --setup-all

This installs dependencies and configures @blitzdev/iphone-mcp for all your AI agents. It automatically sets up Claude Code, Cursor, Codex, OpenCode.

NOTE: For Cursor, you need to enable the blitz-iphone MCP server in Cursor Settings

Project-scoped (one project only)

cd <your project>
npx @blitzdev/iphone-mcp --setup-here

This prompts you to choose which AI agents to configure (Claude Code, Cursor, Codex, OpenCode) and writes the config files into your project directory. @blitzdev/iphone-mcp will only be available when you open an agent inside that directory.

Then just ask

Open a new AI agent session and ask:

> scan the simulator screen and tell me what you see

> connect to my iPhone and test the login flow

> find bugs in my app — tap around, try edge cases, report anything weird

What can it do?

Capability	Simulator	Physical iPhone
Tap, swipe, type text	Yes	Yes
Press buttons (Home, Lock, Siri)	Yes	Yes
Scan UI elements with coordinates	Yes	Yes
Take screenshots	Yes	Yes
List & launch installed apps	Yes	Yes
Auto-detect devices	Yes	Yes
Live screen viewer in browser	--	Yes

iPhones

Connect your iPhone via USB or make sure it's on the same Wi-Fi network (home/office networks work, public cafe Wi-Fi won't).

First-time setup — your iPhone needs:

1. Developer Mode enabled (Settings > Privacy & Security > Developer Mode)
2. Trust this computer when prompted on the phone

Then ask your agent:

> connect to my iPhone

The agent will build and install WebDriverAgent on your phone (takes 1-3 minutes the first time), then give you a URL like http://localhost:5152?udid=... — open it in your browser to see a live view of your phone screen.

Simulators

Boot any iPhone simulator, then ask your AI agent to interact with it. No extra setup needed beyond --setup-all or --setup-here.

> what apps are installed on the simulator?
> launch Safari and go to example.com
> take a screenshot

Example session

You:    test the checkout flow in my app
Agent:  Let me scan the simulator to see what's on screen.

        [calls scan_ui]

        I can see the home screen. Let me launch your app first.

        [calls launch_app with bundleId "com.myapp"]
        [calls get_screenshot]

        The app is open on the main screen. I see a "Shop" tab at the bottom.
        Let me tap it and walk through the checkout flow.

        [calls device_action: tap on "Shop" tab]
        [calls scan_ui]

        I see a list of products. Let me add one to cart...

MCP Tools reference

These are the tools your AI agent can call:

Tool	What it does
get_execution_context	Find available simulators and iPhones
scan_ui	Find tappable elements — buttons, links, text fields — with their coordinates
describe_screen	Full UI element hierarchy (more detail than scan_ui)
device_action	Tap, swipe, press buttons, type text, press keys
device_actions	Run multiple actions in sequence
get_screenshot	Save a screenshot and return the file path
list_devices	List all simulators and physical devices
launch_app	Launch an app by bundle ID
list_apps	List installed apps
setup_device	Build & install WebDriverAgent on a physical iPhone

Manual MCP configuration

If you'd rather configure things yourself:

Claude Code — add to ~/.claude.json (global) or .mcp.json (project):

{
  "mcpServers": {
    "blitz-iphone": {
      "command": "npx",
      "args": ["@blitzdev/iphone-mcp"]
    }
  }
}

Cursor — add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "blitz-iphone": {
      "command": "npx",
      "args": ["@blitzdev/iphone-mcp"]
    }
  }
}

Codex — add to ~/.codex/config.toml (global) or .codex/config.toml (project):

[mcp_servers.blitz-iphone]
command = "npx"
args = ["@blitzdev/iphone-mcp"]

OpenCode — add to opencode.json in your project root:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "blitz-iphone": {
      "type": "local",
      "command": ["npx", "-y", "@blitzdev/iphone-mcp"],
      "enabled": true
    }
  }
}

Troubleshooting

"No booted simulator found" — Open Simulator.app or run xcrun simctl boot "iPhone 16" first.

Physical device not detected — Make sure Developer Mode is on, the phone is connected via USB, and you've tapped "Trust" on the phone.

WDA build fails — Open Xcode > Settings > Accounts and make sure an Apple ID is signed in. Xcode needs a signing identity to build WDA.

"Connection refused" errors — The idb companion may have crashed. Run npx @blitzdev/iphone-mcp --setup-all again to re-initialize.

License

MIT