Back to search
iPhone-mcp
MCP serverGitHub
The MCP Server the lets AI use an iPhone
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/blitzdotdev--iphone-mcp)HTML
<a href="/listings/blitzdotdev--iphone-mcp"><img src="/api/listings/blitzdotdev--iphone-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
npm install @blitzdev/iphone-mcp
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 221 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <div align="center">
- <img src="https://raw.githubusercontent.com/blitzdotdev/iPhone-mcp/refs/heads/master/BlitzBlue.png" width="100" />
- <br /><br />
- <p>iPhone MCP server that lets AI use iPhones</p>
- [](https://blitz.dev/)
- [](https://discord.gg/wJQ6dA95S6)
- [](https://www.npmjs.com/package/@blitzdev/iphone-mcp)
- </div>
- # 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.
- [<video src="https://github.com/blitzdotdev/iPhone-mcp/raw/refs/heads/master/demo.mp4" autoplay loop muted playsinline width="100%"></video>
- ](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.
- <i>NOTE: For Cursor, you need to enable the blitz-iphone MCP server in Cursor Settings</i>
- ### Project-scoped (one project only)
- ```bash
- 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
- ```
- <!-- NOTE: Video showing Claude Code responding to "test my app", scanning UI, tapping buttons, finding a bug, and screenshotting the result -->
- ## 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 |
- <!-- NOTE: Image showing a split view — left side has Claude Code terminal with scan_ui output, right side shows the corresponding simulator screen with UI elements highlighted -->
- ## 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.
- <!-- NOTE: Image showing the browser-based viewer with an iPhone screen displayed in a dark bezel frame -->
- ## 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
- ```
- <!-- NOTE: Image showing terminal output of the list_apps tool with clean formatted app list -->
- ## 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...
- ```
- <!-- NOTE: Video showing a full end-to-end testing session — agent launches app, navigates through screens, finds a UI bug, screenshots it, and reports the issue -->
- ## 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
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.