Repolode
Submit
jfarcand

jfarcand/mirroir-mcp

An MCP server that lets any AI agent drive a stock iPhone through macOS iPhone Mirroring, with no Developer Mode, Xcode or WebDriverAgent.

View on GitHubWebsite
Stars
281
Forks
38
Open issues
3
Last commit
21 hours ago

What is it?

mirroir-mcp is an MCP server for macOS that drives a real, unmodified iPhone through Apple's iPhone Mirroring feature. An AI client can observe the screen with OCR or vision, then tap, swipe, type and press system keys. Because it works on the phone's own screen, it can reach App Store apps the user could not build or instrument themselves.

Beyond the basic control loop, it provides a set of higher-level tools for navigation, scrolling and app lifecycle. An agent can explore an app breadth-first and generate SKILL.md workflows. Skills can be compiled to replay without an LLM via the `mirroir test` CLI, with JUnit output and a distinct drift verdict for CI use.

The project also includes `mirroir-run`, a Rust runner that combines iPhone steps with web (Playwright), HTTP and subprocess steps in one scenario. Its iOS leg requires a Mac with iPhone Mirroring connected; the other surfaces run on Linux.

Key features

  • 01Controls a stock iPhone through iPhone Mirroring with tap, swipe, type and key input.
  • 02Reads the screen via Apple Vision OCR, optional YOLO icon detection, or AI vision mode.
  • 03Works with any MCP client, exposing 38 tools.
  • 04Explores apps and generates replayable SKILL.md skills.
  • 05Replays compiled skills from the CLI without an LLM, with JUnit reporting.
  • 06Fails closed by default, with permission config and blocked-app lists.

Use cases

  • Running end-to-end smoke tests on App Store apps that cannot be instrumented.
  • Letting an AI assistant perform everyday phone tasks such as sending messages or creating calendar events.
  • Recording a manual walkthrough and replaying it as a CI scenario.
  • Combining iPhone checks with web page checks in a single cross-surface test.

Quick start

  1. 1

    Install the server via npx (requires macOS 15+ and iPhone Mirroring)

    npx -y mirroir-mcp install
  2. 2

    Grant Screen Recording and Accessibility permissions when macOS prompts on the first screenshot

  3. 3

    Register mirroir with Claude Code as an MCP server

    claude mcp add --transport stdio mirroir -- npx -y mirroir-mcp

Things to know

  • Works only on macOS 15+ with iPhone Mirroring; it does not support Android or the iOS Simulator.
  • Games with twitch or multi-touch controls are out of reach because iPhone Mirroring exposes a single pointer.

In collections

MCP servers for Claude CodeClaude Code tools, skills & pluginsOpen-source AI agent frameworks & appsMCP serversOpen-source Mac appsTesting frameworks & test automation tools

Topics

#mcp#ios-automation#mobile-testing#computer-use#ai-agent#macos#test-automation#ai-testing#appium-alternative#claude-code

FAQ

What is mirroir-mcp?
An MCP server that lets any AI agent drive a stock iPhone through macOS iPhone Mirroring, with no Developer Mode, Xcode or WebDriverAgent. mirroir-mcp is an MCP server for macOS that drives a real, unmodified iPhone through Apple's iPhone Mirroring feature. An AI client can observe the screen with OCR or vision, then tap, swipe, type and press system keys. Because it works on the phone's own screen, it can reach App Store apps the user could not build or instrument themselves.
Is mirroir-mcp free to use? What license does it have?
mirroir-mcp is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is mirroir-mcp still maintained?
Actively maintained. The last commit to mirroir-mcp was on Nov 6, 2026.
What can I use mirroir-mcp for?
Running end-to-end smoke tests on App Store apps that cannot be instrumented. Letting an AI assistant perform everyday phone tasks such as sending messages or creating calendar events. Recording a manual walkthrough and replaying it as a CI scenario. Combining iPhone checks with web page checks in a single cross-surface test.
How do I install mirroir-mcp?
Install the server via npx (requires macOS 15+ and iPhone Mirroring): npx -y mirroir-mcp install Grant Screen Recording and Accessibility permissions when macOS prompts on the first screenshot Register mirroir with Claude Code as an MCP server: claude mcp add --transport stdio mirroir -- npx -y mirroir-mcp
Where can I get mirroir-mcp?
The source code and installation instructions are on GitHub: https://github.com/jfarcand/mirroir-mcp

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects