Skip to content
Back to search

iPhone-mcp

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/blitzdotdev--iphone-mcp/badge.svg)](/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)

  1. <div align="center">
  2. <img src="https://raw.githubusercontent.com/blitzdotdev/iPhone-mcp/refs/heads/master/BlitzBlue.png" width="100" />
  3. <br /><br />
  4. <p>iPhone MCP server that lets AI use iPhones</p>
  5. [![Website](https://img.shields.io/badge/blitz.dev-website-black)](https://blitz.dev/)
  6. [![Discord](https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/wJQ6dA95S6)
  7. [![npm](https://img.shields.io/npm/v/@blitzdev/iphone-mcp?label=npm&color=blue)](https://www.npmjs.com/package/@blitzdev/iphone-mcp)
  8. </div>
  9. # iPhone-mcp
  10. MCP server that lets AI agents control real iPhones and iPhone simulators on MacOS.
  11. Works with Claude Code, Cursor, Codex, OpenCode, and any MCP-compatible AI agent.
  12. [<video src="https://github.com/blitzdotdev/iPhone-mcp/raw/refs/heads/master/demo.mp4" autoplay loop muted playsinline width="100%"></video>
  13. ](https://github.com/user-attachments/assets/b210df5a-ed09-4efd-9c95-d69021fd3d46)
  14. ## Requirements
  15. - macOS
  16. - Xcode (install from App Store or `xcode-select --install`)
  17. - Node.js 18+
  18. - Homebrew
  19. ## Installation
  20. ```bash
  21. npm install @blitzdev/iphone-mcp
  22. ```
  23. ## Quick Start
  24. ### Global (use in any project)
  25. ```bash
  26. npx @blitzdev/iphone-mcp --setup-all
  27. ```
  28. This installs dependencies and configures `@blitzdev/iphone-mcp` for all your AI agents. It automatically sets up Claude Code, Cursor, Codex, OpenCode.
  29. <i>NOTE: For Cursor, you need to enable the blitz-iphone MCP server in Cursor Settings</i>
  30. ### Project-scoped (one project only)
  31. ```bash
  32. cd <your project>
  33. npx @blitzdev/iphone-mcp --setup-here
  34. ```
  35. 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.
  36. ### Then just ask
  37. Open a new AI agent session and ask:
  38. ```
  39. > scan the simulator screen and tell me what you see
  40. ```
  41. ```
  42. > connect to my iPhone and test the login flow
  43. ```
  44. ```
  45. > find bugs in my app — tap around, try edge cases, report anything weird
  46. ```
  47. <!-- NOTE: Video showing Claude Code responding to "test my app", scanning UI, tapping buttons, finding a bug, and screenshotting the result -->
  48. ## What can it do?
  49. | Capability | Simulator | Physical iPhone |
  50. |---|---|---|
  51. | Tap, swipe, type text | Yes | Yes |
  52. | Press buttons (Home, Lock, Siri) | Yes | Yes |
  53. | Scan UI elements with coordinates | Yes | Yes |
  54. | Take screenshots | Yes | Yes |
  55. | List & launch installed apps | Yes | Yes |
  56. | Auto-detect devices | Yes | Yes |
  57. | Live screen viewer in browser | -- | Yes |
  58. <!-- 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 -->
  59. ## iPhones
  60. 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).
  61. **First-time setup** — your iPhone needs:
  62. 1. **Developer Mode** enabled (Settings > Privacy & Security > Developer Mode)
  63. 2. **Trust this computer** when prompted on the phone
  64. Then ask your agent:
  65. ```
  66. > connect to my iPhone
  67. ```
  68. 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.
  69. <!-- NOTE: Image showing the browser-based viewer with an iPhone screen displayed in a dark bezel frame -->
  70. ## Simulators
  71. Boot any iPhone simulator, then ask your AI agent to interact with it. No extra setup needed beyond `--setup-all` or `--setup-here`.
  72. ```
  73. > what apps are installed on the simulator?
  74. > launch Safari and go to example.com
  75. > take a screenshot
  76. ```
  77. <!-- NOTE: Image showing terminal output of the list_apps tool with clean formatted app list -->
  78. ## Example session
  79. ```
  80. You: test the checkout flow in my app
  81. Agent: Let me scan the simulator to see what's on screen.
  82. [calls scan_ui]
  83. I can see the home screen. Let me launch your app first.
  84. [calls launch_app with bundleId "com.myapp"]
  85. [calls get_screenshot]
  86. The app is open on the main screen. I see a "Shop" tab at the bottom.
  87. Let me tap it and walk through the checkout flow.
  88. [calls device_action: tap on "Shop" tab]
  89. [calls scan_ui]
  90. I see a list of products. Let me add one to cart...
  91. ```
  92. <!-- 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 -->
  93. ## MCP Tools reference
  94. These are the tools your AI agent can call:
  95. | Tool | What it does |
  96. |---|---|
  97. | `get_execution_context` | Find available simulators and iPhones |
  98. | `scan_ui` | Find tappable elements — buttons, links, text fields — with their coordinates |
  99. | `describe_screen` | Full UI element hierarchy (more detail than scan_ui) |
  100. | `device_action` | Tap, swipe, press buttons, type text, press keys |
  101. | `device_actions` | Run multiple actions in sequence |
  102. | `get_screenshot` | Save a screenshot and return the file path |
  103. | `list_devices` | List all simulators and physical devices |
  104. | `launch_app` | Launch an app by bundle ID |
  105. | `list_apps` | List installed apps |
  106. | `setup_device` | Build & install WebDriverAgent on a physical iPhone |
  107. ## Manual MCP configuration
  108. If you'd rather configure things yourself:
  109. **Claude Code** — add to `~/.claude.json` (global) or `.mcp.json` (project):
  110. ```json
  111. {
  112. "mcpServers": {
  113. "blitz-iphone": {
  114. "command": "npx",
  115. "args": ["@blitzdev/iphone-mcp"]
  116. }
  117. }
  118. }
  119. ```
  120. **Cursor** — add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
  121. ```json
  122. {
  123. "mcpServers": {
  124. "blitz-iphone": {
  125. "command": "npx",
  126. "args": ["@blitzdev/iphone-mcp"]
  127. }
  128. }
  129. }
  130. ```
  131. **Codex** — add to `~/.codex/config.toml` (global) or `.codex/config.toml` (project):
  132. ```toml
  133. [mcp_servers.blitz-iphone]
  134. command = "npx"
  135. args = ["@blitzdev/iphone-mcp"]
  136. ```
  137. **OpenCode** — add to `opencode.json` in your project root:
  138. ```json
  139. {
  140. "$schema": "https://opencode.ai/config.json",
  141. "mcp": {
  142. "blitz-iphone": {
  143. "type": "local",
  144. "command": ["npx", "-y", "@blitzdev/iphone-mcp"],
  145. "enabled": true
  146. }
  147. }
  148. }
  149. ```
  150. ## Troubleshooting
  151. **"No booted simulator found"** — Open Simulator.app or run `xcrun simctl boot "iPhone 16"` first.
  152. **Physical device not detected** — Make sure Developer Mode is on, the phone is connected via USB, and you've tapped "Trust" on the phone.
  153. **WDA build fails** — Open Xcode > Settings > Accounts and make sure an Apple ID is signed in. Xcode needs a signing identity to build WDA.
  154. **"Connection refused" errors** — The idb companion may have crashed. Run `npx @blitzdev/iphone-mcp --setup-all` again to re-initialize.
  155. ## License
  156. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.