iPhone MCP server that lets AI use iPhones
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.
demo.mp4
- macOS
- Xcode (install from App Store or
xcode-select --install) - Node.js 18+
- Homebrew
npm install @blitzdev/iphone-mcpnpx @blitzdev/iphone-mcp --setup-allThis 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
cd <your project>
npx @blitzdev/iphone-mcp --setup-hereThis 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.
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
| 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 |
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:
- Developer Mode enabled (Settings > Privacy & Security > Developer Mode)
- 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.
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
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...
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 |
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
}
}
}"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.
MIT