Skip to content
Back to search

mirroir-mcp

MCP server for controlling a real iPhone via macOS iPhone Mirroring...and any MacOs app. Screenshot, tap, swipe, type — from any MCP client.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/jfarcand/mirroir-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/jfarcand/mirroir-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jfarcand--mirroir-mcp/badge.svg)](/listings/jfarcand--mirroir-mcp)

HTML

<a href="/listings/jfarcand--mirroir-mcp"><img src="/api/listings/jfarcand--mirroir-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.

You need macOS 15 or later and an iPhone connected through [iPhone Mirroring](https://support.apple.com/en-us/105071). Paste this into your coding agent (Claude Code, Codex, Cursor, OpenClaw, …):

Set up mirroir-mcp so you can drive my iPhone: follow https://github.com/jfarcand/mirroir-mcp/blob/main/docs/onboarding.md step by step, and finish by reading back what my iPhone screen shows.

Or install it yourself:

npx -y mirroir-mcp install    # or: brew tap jfarcand/tap && brew install mirroir-mcp
npx -y mirroir-mcp doctor     # names anything left to fix

OpenClaw, Claude Desktop, Cursor, VS Code and the other clients: [Install](docs/install.md).

Then ask for something:

Open Calendar, create a new event called "Dentist" next Tuesday at 2pm.
Open my Expo Go app, tap "LoginDemo", test the login screen with
test@example.com / password123. Screenshot after each step.
Start recording, open Instagram, scroll the feed and open my profile, stop recording.

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.

.claude-plugin/marketplace.json · Manifest · 26 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "mirroir",
  4. "description": "mirroir: drive a real iPhone from Claude Code through macOS iPhone Mirroring, plus the community skill library.",
  5. "owner": {
  6. "name": "Jean-Francois Arcand",
  7. "url": "https://github.com/jfarcand"
  8. },
  9. "plugins": [
  10. {
  11. "name": "mirroir",
  12. "source": "./plugins/mirroir",
  13. "description": "Registers the mirroir MCP server (npx -y mirroir-mcp): screenshot, OCR, tap, swipe and type on a real iPhone through macOS iPhone Mirroring.",
  14. "category": "automation"
  15. },
  16. {
  17. "name": "skills",
  18. "source": {
  19. "source": "github",
  20. "repo": "jfarcand/mirroir-skills"
  21. },
  22. "description": "Skill execution: teaches the AI how to interpret and run mirroir skills (SKILL.md and YAML) from the mirroir-skills library.",
  23. "category": "automation"
  24. }
  25. ]
  26. }
README.md · README · 163 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="website/public/mirroir-wordmark.svg" alt="mirroir-mcp" width="128" />
  3. </p>
  4. # mirroir-mcp
  5. [![npm version](https://img.shields.io/npm/v/mirroir-mcp)](https://www.npmjs.com/package/mirroir-mcp)
  6. [![Build](https://github.com/jfarcand/mirroir-mcp/actions/workflows/build.yml/badge.svg)](https://github.com/jfarcand/mirroir-mcp/actions/workflows/build.yml)
  7. [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
  8. [![macOS 15+](https://img.shields.io/badge/macOS-15%2B-black?logo=apple)](https://support.apple.com/en-us/120421)
  9. [![Discord](https://img.shields.io/discord/1481795325953048627?logo=discord&label=Discord)](https://discord.gg/u8ug9QCSqF)
  10. ### Let your agent use your real iPhone: errands across your apps, automations, even games.
  11. <p align="center">
  12. <a href="https://mirroir.dev/?utm_source=github&utm_medium=readme&utm_campaign=header">Website</a> ·
  13. <a href="https://mirroir.dev/?utm_source=github&utm_medium=readme&utm_campaign=header#demo">Demos</a> ·
  14. <a href="docs/onboarding.md">Set up with your agent</a> ·
  15. <a href="docs/tools.md">Tools</a> ·
  16. <a href="CHANGELOG.md">Changelog</a> ·
  17. <a href="https://discord.gg/u8ug9QCSqF">Discord</a>
  18. </p>
  19. <p align="center">
  20. <img src="website/public/recipe-grocery-list.gif" alt="The Claude app and a real iPhone side by side: the agent opens a saved Instagram recipe reel, listens to it, then writes an eleven-item grocery list in Reminders" width="720" />
  21. </p>
  22. <p align="center"><em>A saved recipe reel becomes a grocery list in Reminders. The agent listens to the video and reads its frames. A real iPhone, sped up.</em></p>
  23. No Developer Mode, no Xcode, no WebDriverAgent, no jailbreak. mirroir-mcp works through macOS iPhone Mirroring, so it reaches any app on your phone, including App Store apps you could never build. It works from any MCP client, with [42 tools](docs/tools.md).
  24. It uses the apps already signed in on your phone: no connector, no OAuth, no password handed to anyone.
  25. ## What people build
  26. - **A saved recipe reel becomes a grocery list.** The agent opens the reel, reads its frames with `describe_screen`, hears the narration with [`listen`](docs/tools.md#listening), then types the ingredients into Reminders. That is the run in the GIF above.
  27. - **Errands across apps.** Read the commute time in Waze, then post it in Slack: the agent carries what one app shows into another. [Watch the demo](https://mirroir.dev/?utm_source=github&utm_medium=readme&utm_campaign=body#demo). The same errand as a skill (Waze to Messages) is in [Skills, exploration and CI](docs/skills-and-ci.md#skills).
  28. - **Games.** A [`scene:` step](docs/skills-marketplace.md#scenes) plays a turn-based or tap-driven game, frame by frame, under a hard frame, token and time budget; a run that runs out of budget is inconclusive (exit 66), never a silent pass. [`touch`](docs/tools.md#games-and-multi-touch) holds a finger for virtual joysticks, `hold_keys` drives games that take keyboard and mouse, and `pinch` and `rotate` zoom and rotate. iPhone Mirroring exposes a single pointer, so twin-stick games stay out of reach. See [Games](docs/games.md).
  29. <p align="center">
  30. <img src="website/public/chess-vs-maximum.gif" alt="The console and a real iPhone side by side during a full chess game: each move is logged as it is played, ending in checkmate against the Maximum bot on Chess.com" width="720" />
  31. </p>
  32. <p align="center"><em>A real game on a real iPhone: the model reads the board, Stockfish picks the moves, mirroir plays them against Chess.com's strongest bot. The opening runs at 2.5×, the middle game at 45×, the finish at 2×.</em></p>
  33. ## Quick start
  34. You need macOS 15 or later and an iPhone connected through [iPhone Mirroring](https://support.apple.com/en-us/120421). Paste this into your coding agent (Claude Code, Codex, Cursor, OpenClaw, …):
  35. ```text
  36. Set up mirroir-mcp so you can drive my iPhone: follow https://github.com/jfarcand/mirroir-mcp/blob/main/docs/onboarding.md step by step, and finish by reading back what my iPhone screen shows.
  37. ```
  38. Or install it yourself:
  39. ```bash
  40. npx -y mirroir-mcp install # or: brew tap jfarcand/tap && brew install mirroir-mcp
  41. npx -y mirroir-mcp doctor # names anything left to fix
  42. ```
  43. OpenClaw, Hermes Agent, Claude Desktop, Cursor, VS Code and the other clients: [Install](docs/install.md).
  44. Then ask for something:
  45. ```
  46. Open Calendar, create a new event called "Dentist" next Tuesday at 2pm.
  47. ```
  48. ```
  49. Open my Expo Go app, tap "LoginDemo", test the login screen with
  50. test@example.com / password123. Screenshot after each step.
  51. ```
  52. ```
  53. Start recording, open Instagram, scroll the feed and open my profile, stop recording.
  54. ```
  55. ## Build your own agent
  56. - **Any MCP client.** Claude Code, Codex, Cursor, VS Code, Claude Desktop and the others connect to the same [42 tools](docs/tools.md). It also installs as a Claude Code plugin, an OpenClaw skill from ClawHub, or a Hermes Agent plugin that asks before every call that can change the phone: see [Install](docs/install.md).
  57. - **Proven steps in one call.** Once a sequence has worked, [`run_steps`](docs/tools.md#tool-list) replays it in one call (`"tap: <text on screen>"`, `"type: calculator"`, `"wait_for: Get"`). Every step is checked against the permission policy before the first runs, and the run stops at the first failure.
  58. - **Skills.** Capture a workflow you repeat as a [SKILL.md](docs/skills-and-ci.md#skills): numbered steps the AI follows, matched on screen text, not coordinates. `generate_skill` explores an app and writes them for you. Ready-made skills live in [mirroir-skills](https://github.com/jfarcand/mirroir-skills); the format is in [Skills Marketplace](docs/skills-marketplace.md).
  59. - **Agents keep notes.** `save_note` keeps one line per lesson per app, and `get_notes` gives it to the next session.
  60. - **An agent on another machine.** [`mirroir-mcp serve`](docs/cli.md#serve) speaks MCP over HTTP on 127.0.0.1 only, behind a bearer token; reach it through an SSH port forward. `install-agent` keeps it running as a LaunchAgent from its own signed "mirroir serve" bundle, so its grants survive upgrades.
  61. ## Why mirroir
  62. - **Nothing to install on the phone.** The iPhone stays stock: no signing, no provisioning profile, no on-device agent. If iPhone Mirroring shows it, mirroir can drive it.
  63. - **Your Mac stays yours.** Taps, typing and swipes reach the mirror without bringing it to the front, so you can keep working. Drags and two-finger gestures bring it forward for a moment, then hand your app back.
  64. - **It hears the phone, too.** [`listen`](docs/tools.md#listening) turns what the phone plays, a reel's narration or a voice message, into text. It records only iPhone Mirroring's sound, and macOS transcribes it on the Mac: the audio never leaves it. Needs macOS 26; since 0.47.0.
  65. ## Testing and CI
  66. The run an agent makes once can become a test that runs without it.
  67. - **Explore once, replay without an LLM.** `generate_skill` explores an app and writes [SKILL.md](docs/skills-and-ci.md#skills) files. A compiled skill replays from the CLI with no AI in the loop (`mirroir test`), so CI runs are deterministic and cost no tokens.
  68. - **One test across phone, web and backend.** [`mirroir-run`](docs/mirroir-run.md) is our companion test runner, a separate binary. One YAML scenario can drive the iPhone, a browser, HTTP endpoints and subprocesses, then compare what the page and the phone showed. See [Web and iOS in one scenario](docs/web-and-ios.md).
  69. - **Drift fails loudly.** `mirroir-run` has a third verdict beside pass and fail: `DRIFT`, exit code **65**, when every assertion held but the output moved past its baseline. Your CI lane decides whether drift blocks a merge.
  70. ### How it compares
  71. | | mirroir | [phone-harness](https://github.com/phone-harness/phone-harness) | [mobile-mcp](https://github.com/mobile-next/mobile-mcp) | [Appium](https://github.com/appium/appium) |
  72. |---|---|---|---|---|
  73. | Physical iPhone, no Developer Mode or signing | Yes — stock phone via iPhone Mirroring | Yes — stock phone via iPhone Mirroring | USB-connected, trusted device (see its README) | No — WebDriverAgent via Xcode, Developer Mode |
  74. | App Store apps you can't build | Yes | Yes | Yes | Yes, on a provisioned device |
  75. | Your own iPhone from any MCP client | Yes | No — its MCP server is cloud-only; local phones use its CLI | Yes | Through the separate [appium-mcp](https://github.com/appium/appium-mcp) |
  76. | Replay without an LLM | Yes — compiled skills, `mirroir test` | Python scripts you write; no recorder or compiled replay | No — the agent drives every run | Yes — test code |
  77. | Distinct drift verdict | Yes — `DRIFT`, exit 65 | No | No | No — pass / fail |
  78. | One scenario across iPhone + web + HTTP | Yes — `mirroir-run` | No | No | Via your own test code |
  79. | Android | No — an emulator window can be driven only as a generic macOS window | Yes | Yes | Yes |
  80. | iOS Simulator | No | No | Yes | Yes |
  81. | Hosted cloud phones | No | Yes — Phone Harness Cloud | Yes — Mobile Next Cloud | Via third-party device clouds |
  82. phone-harness is the closest tool here: it also drives a stock iPhone through iPhone Mirroring, and it adds Android and hosted phones, which mirroir doesn't have. mobile-mcp and Appium cover Android and simulators too. mirroir goes further after the agent's first run: that run becomes a replay that needs no LLM, and a test that tells you when the output moves.
  83. ## Safety
  84. Giving an AI access to your phone demands defense in depth, so mirroir-mcp is **fail-closed**.
  85. - **Read-only until you say otherwise.** Without a config file, only the 14 read-only tools are exposed. Every tool that changes something stays hidden from the client until you allow it in [`permissions.json`](docs/permissions.md).
  86. - **Sensitive apps can be blocked.** `blockedApps` keeps the AI out of apps like Wallet or Banking, even when other tools are allowed.
  87. - **Passwords stay yours.** mirroir never presses a sheet that asks for a password or Touch ID, and it tells agents to ask you before sending, buying, deleting or changing a setting.
  88. - **No root, no telemetry, no daemon unless you install one.** It runs as your user with Screen Recording and Accessibility, and lives and dies with your MCP client; only the opt-in [`serve` agent](docs/security.md) keeps running, on loopback, behind a token. The one network call it makes by default is a once-a-day version check against npm (`updateCheck: false` turns it off). What your agent reads from the screen goes to whichever model your client uses.
  89. - **Kill switch.** Quit iPhone Mirroring, unlock the iPhone, lock the Mac's screen, or quit your MCP client: each stops all input at once, and nothing reopens the app for the agent.
  90. See [Security](docs/security.md) for the full threat model.
  91. ## Documentation
  92. | | |
  93. |---|---|
  94. | [Install](docs/install.md) | Every install path, per-client setup, updating, uninstalling |
  95. | [Onboarding](docs/onboarding.md) | Setup written for the agent: prerequisites, install, doctor, a read-only proof, and an optional first errand |
  96. | [Tools Reference](docs/tools.md) | All 42 tools, parameters, and input workflows |
  97. | [How mirroir sees the screen](docs/screen-intelligence.md) | The observe, reason, act loop; OCR, icon detection, AI vision |
  98. | [Skills, exploration and CI](docs/skills-and-ci.md) | APP.md, skills, `generate_skill`, `mirroir test`, compiled replay, AI diagnosis, patterns |
  99. | [`mirroir-run`](docs/mirroir-run.md) | Replay across iPhone, web, HTTP and subprocesses; GitHub Actions; Maestro import |
  100. | [Games](docs/games.md) | Shell and scene, the `scene:` step, game controls |
  101. | [CLI Tools](docs/cli.md) | Recorder, doctor, keyboard layout, `serve` over HTTP |
  102. | [Configuration](docs/configuration.md) | All settings: screen intelligence, input timing, exploration, AI providers |
  103. | [FAQ](docs/faq.md) | Security, focus stealing, keyboard layouts, embacle/vision mode |
  104. | [Security](docs/security.md) | Threat model, kill switch, and recommendations |
  105. | [Privacy](docs/privacy.md) | What mirroir reads, sends and stores |
  106. | [Permissions](docs/permissions.md) | Fail-closed permission model and config file |
  107. | [Known Limitations](docs/limitations.md) | Focus stealing, keyboard layout gaps, autocorrect |
  108. | [Patterns & Skills](docs/components.md) | Element patterns, screen recipes, APP.md app descriptions, and the detection pipeline |
  109. | [Exploring a New App](docs/exploring-a-new-app.md) | Step-by-step playbook for onboarding a new app — APP.md, permissions, components, exploration goal |
  110. | [YOLO Icon Detection](docs/yolo-models.md) | Recommended YOLO models, CoreML setup, and configuration |
  111. | [Compiled Skills](docs/compiled-skills.md) | Zero-OCR skill replay |
  112. | [Testing](docs/testing.md) | FakeMirroring, integration tests, and CI strategy |
  113. | [Web and iOS in one scenario](docs/web-and-ios.md) | How `mirroir-run` hands iOS blocks to `mirroir-mcp`, and how `cross_surface` compares a browser with a phone |
  114. | [Cross-surface replay](runner/docs/) | `mirroir-run` scenario grammar, `.mirroir/` plan, `SAMPLE.md`, judge profiles, CI |
  115. | [Troubleshooting](docs/troubleshooting.md) | Debug mode and common issues |
  116. | [Contributing](CONTRIBUTING.md) | How to add tools, commands, and tests |
  117. | [Skills Marketplace](docs/skills-marketplace.md) | Skill format, plugin discovery, and authoring |
  118. ## Community
  119. Join the [Discord server](https://discord.gg/u8ug9QCSqF) to ask questions, share skills, and discuss ideas. Contributions are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md). By submitting a patch, you agree to the [Contributor License Agreement](CLA.md); your Git commit metadata serves as your electronic signature.
  120. ---
  121. Apache 2.0 - Copyright 2026 [Async-IO](https://async-io.live).
  122. > **Why "mirroir"?** — It's the old French spelling of *miroir* (mirror). A nod to the author's roots, not a typo.

Ratings and comments

Sign in to rate this skill.

Sign in

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