mirroir-mcp
An MCP server that drives a real iPhone through macOS iPhone Mirroring: the agent sees the screen, taps, swipes and types
- 270 ★ on the repository
- Last commit
- Apache-2.0
Broad access
Why this level
- The agent controls a real phone: taps, text input, launching and closing apps
- The screen can show private messages, mail and banking apps, and screenshots go to the model
- Without a permissions file only 11 non-mutating tools are available, and action rights are opened by hand
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/mirroir-mcpDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent controls a real phone: taps, text input, launching and closing apps
- The screen can show private messages, mail and banking apps, and screenshots go to the model
- Without a permissions file only 11 non-mutating tools are available, and action rights are opened by hand
This is third-party code. Review the repository files before installing.
What it does
mirroir-mcp connects an agent to a real iPhone through the macOS iPhone Mirroring feature. The Swift server exposes 38 tools: `screenshot`, `describe_screen`, `tap`, `swipe`, `type_text`, `press_home`, `scroll_to`, `reset_app` and more. It works in a loop of look, think, act: `describe_screen` returns every text element with tap coordinates, the model decides what to press and the action runs. Apple Vision recognises on-screen text right on your Mac and needs no API keys. If you drop a YOLO model in CoreML format into `~/.mirroir-mcp/models/`, the server adds icons and toggles to the text. An AI vision mode also exists, where the screenshot goes to a model that understands the interface semantically. Windows of other macOS apps are supported experimentally. Repeated flows are written as skills in SKILL.md files: numbered steps such as `Tap "Email"`, with no hard-coded coordinates. An `APP.md` file describes the app (tabs, permission dialogs, what to skip) and exploration uses those hints. `mirroir test` runs skills as tests, `mirroir record` saves actions to YAML and `mirroir doctor` checks the setup. Games get special attention: shell screens (menus, shop, settings) work today, while playing the scene itself is limited by the single pointer of iPhone Mirroring.
Who it is for. For mobile developers and testers with a Mac on macOS 15 and an iPhone who want Claude Code, Cursor or Codex to run scenarios on a real device.
Good fit when
- You need to test an app on a real iPhone rather than a simulator: sign-in, checkout, system dialogs
- A check repeats and fits a skill that runs through `mirroir test` in CI
- You need to explore an unfamiliar app: the explorer walks screens, scrolls and builds a map of transitions
- You need a quick smoke test of a mobile game: menus, shop, win and lose screens
- You want the agent to handle phone routine: send a message, create a calendar event, change a setting
Not a fit when
- You have no Mac on macOS 15 and no iPhone connected through iPhone Mirroring: the server will not run
- You need real-time games with two fingers: iPhone Mirroring has a single pointer
- You need access to Wallet, banking apps or other sensitive screens: close them off with `blockedApps` instead
- You are testing Android: the server works only with iPhone and macOS windows
Example request
Open Calendar on the iPhone, create an event called Dentist next Tuesday at 2pm and send me a screenshot of the result.MCP
- Transport
- stdio
- Authentication
- not required
Limitations
- Requires macOS 15 or newer and an iPhone connected through iPhone Mirroring. At the first screenshot macOS asks for Screen Recording and Accessibility permissions.
- Without a config file the server shows the client only 11 tools that change nothing. Taps, text input and app launches are opened through `~/.mirroir-mcp/permissions.json`.
- iPhone Mirroring passes apps a single touch, so two-finger gestures and games with two joysticks are out of reach.
- macOS window support and the AI vision mode are marked experimental in the documentation.
- Each screenshot costs the model a few thousand tokens, and text recognition through `describe_screen` removes most of that load.
How to disable. Remove the `mirroir` entry from the MCP client config, for example with `claude mcp remove mirroir`. To remove the program run `brew uninstall mirroir-mcp` if you installed through Homebrew. Closing the iPhone Mirroring window stops all input at once.
FAQ
How do I control an iPhone from Claude Code?
Run `claude mcp add --transport stdio mirroir -- npx -y mirroir-mcp` on a Mac with macOS 15, turn on iPhone Mirroring and grant Screen Recording and Accessibility. The agent then sees the screen through `describe_screen` and acts with `tap`, `swipe` and `type_text`.
Why can the agent not tap the screen?
Without `~/.mirroir-mcp/permissions.json` the server hides all mutating tools from the client and leaves 11 safe ones. Add the names you need to the `allow` list, for example `tap` and `type_text`.
Do I need API keys for screen recognition?
No. By default Apple Vision recognises text on the Mac itself. The AI vision mode is optional, and in it a model processes the screenshot.
How do I stop the agent touching banking apps?
List them in the `blockedApps` array of `permissions.json`, for example Wallet and Banking. The block holds even when mutating tools are allowed.
Can a scenario become a CI test?
Yes. Write the scenario as a SKILL.md skill, then `mirroir test` runs it and can save a JSON report. Compiled skills replay without text recognition and run noticeably faster.
Discussion
No questions or reviews yet.
Related
MCP serversAn MCP server for the iOS Simulator: taps, swipes, text input, accessibility tree, screenshots, video and app control
An MCP server that takes plain-language commands and drives the iOS Simulator through idb: apps, taps, logs
An MCP server to drive iOS and Android: simulators, emulators and real devices via accessibility trees and screenshots
Lets Claude Code and Codex drive a real iPhone: read the screen, tap, type and scroll in any app
XcodeBuildMCP (now MobileBuildMCP)
XcodeBuildMCP
An MCP server and CLI from Sentry for building, running and testing Xcode iOS and macOS projects from an AI agent
MCP server for Apple's official developer docs: search frameworks, APIs, code samples and WWDC sessions from your agent
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| mirroir-mcp (this entry) | no | not required | 270 | |
| MCP Server for iOS Simulator | no | not required | 342 | works with the iOS simulator, while here a real iPhone is driven through iPhone Mirroring |
| iOS Simulator Skill | no | 1,303 | a skill for the simulator on a Mac, with no access to a physical phone |
README in short
The page opens with install methods and setup for Claude Code, GitHub Copilot, Cursor and Codex. It continues with the observe and act loop, the `APP.md` file, example prompts, a games section and details of screen recognition. Blocks on skills, tests, security and utility commands close it.