https://github.com/blitzdotdev/iphone-mcp
The MCP Server the lets AI use an iPhone
https://github.com/blitzdotdev/iphone-mcp
Last synced: 2 months ago
JSON representation
The MCP Server the lets AI use an iPhone
- Host: GitHub
- URL: https://github.com/blitzdotdev/iphone-mcp
- Owner: blitzdotdev
- License: mit
- Created: 2026-03-01T04:04:19.000Z (4 months ago)
- Default Branch: master
- Last Pushed: 2026-04-01T06:07:58.000Z (3 months ago)
- Last Synced: 2026-04-01T09:04:19.662Z (3 months ago)
- Language: TypeScript
- Homepage: https://blitz.dev
- Size: 3.2 MB
- Stars: 61
- Watchers: 2
- Forks: 10
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-security - iphone-mcp - iphone-mcp) | (γ«γγ΄γͺ / π οΈ <a name="developer-tools"></a>ιηΊγγΌγ«)
README
iPhone MCP server that lets AI use iPhones
[](https://blitz.dev/)
[](https://discord.gg/wJQ6dA95S6)
[](https://www.npmjs.com/package/@blitzdev/iphone-mcp)
# 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.
[
](https://github.com/user-attachments/assets/b210df5a-ed09-4efd-9c95-d69021fd3d46)
## Requirements
- macOS
- Xcode (install from App Store or `xcode-select --install`)
- Node.js 18+
- Homebrew
## Installation
```bash
npm install @blitzdev/iphone-mcp
```
## Quick Start
### Global (use in any project)
```bash
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)
```bash
cd
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):
```json
{
"mcpServers": {
"blitz-iphone": {
"command": "npx",
"args": ["@blitzdev/iphone-mcp"]
}
}
}
```
**Cursor** β add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
```json
{
"mcpServers": {
"blitz-iphone": {
"command": "npx",
"args": ["@blitzdev/iphone-mcp"]
}
}
}
```
**Codex** β add to `~/.codex/config.toml` (global) or `.codex/config.toml` (project):
```toml
[mcp_servers.blitz-iphone]
command = "npx"
args = ["@blitzdev/iphone-mcp"]
```
**OpenCode** β add to `opencode.json` in your project root:
```json
{
"$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