One MCP server for iOS Simulators and real iPhones.

StupidMirror lists every booted iOS Simulator next to your iPhone and gives Claude Code, Codex and other MCP clients the same tools for both: read the screen, tap, type, install a build, record, verify. It runs on your Mac and needs no model API key.

StupidMirror mirroring an iPhone Air over USB with control ready and MCP on port 17373

Set up in four steps

Needs macOS 15 or later. Download StupidMirror 0.8.5 or later, move it to Applications and open it.

Boot a simulator

Start any iOS Simulator from Xcode. It appears in StupidMirror while it is booted. The screen agent is built for the simulator once, with no signing, and its ports listen on this Mac only.

Or connect an iPhone

Over USB, trust this Mac, turn on Developer Mode and run Set Up This iPhone once. The same setup turns on Wi-Fi connections, so later sessions work without the cable.

Connect your agent

In Settings → MCP Automation, click Connect on the Claude Code card or the Codex card. Parts already installed are skipped.

Ask for a first look

Start a new session and try: “List my devices, open the booted simulator and read the current screen without tapping anything.”

Registered by Connect on the Claude Code card: a stdio bridge, so no token is written to Claude Code's configuration.

claude mcp add --scope user stupidmirror -- /Applications/StupidMirror.app/Contents/Helpers/StupidMirrorMCPBridge --app /Applications/StupidMirror.app

Other MCP clients: Streamable HTTP on localhost (default port), with the bearer token from the generated configuration.

http://127.0.0.1:17373/mcp
Authorization: Bearer <token>

Same tools on simulator and device

Read the screen

observe_screen returns a live frame with local Apple Vision OCR; find_any_element finds a control by any of several labels.

Touch and type

tap_text, tap_element, swipe and long_press. Simulators use simulator system HID; iPhones on iOS 27+ use live system HID, other versions WebDriverAgent. replace_text edits a field and verifies the value.

Install and launch

install_app takes a simulator-built .app for a simulator, or a signed .app or .ipa for an iPhone. open_url opens deep links; activate_app and terminate_app start and stop apps.

Verify

wait_for and assert_screen check that text appears or disappears before the agent moves on.

Record

start_recording saves the live mirror as an .mp4 of up to 10 minutes in ~/Movies/StupidMirror.

Foldable simulators

set_device_posture sets an iPhone Duo simulator to Closed, Partially Open or Open, with a compatible Xcode runtime.

Runs on this Mac

The MCP server listens on 127.0.0.1 only, and the simulator agent's ports stay on this Mac. Capture, playback and OCR run locally; StupidMirror does not upload the screen to a model provider. Your AI client receives the screenshots and tool results it asks for, under its own data settings.

Free for one device

Mirror and control one device at a time without signing in, whether a simulator, an emulator or a real phone. Running several at once, such as a simulator or emulator next to a real phone, needs the iTool yearly membership: ¥99/year with Alipay or US$26.49/year by card. It covers every iTool product; the monthly plan does not include StupidMirror.

iTool yearly membership

Before you buy

Does it work with the iOS Simulator?

Yes. Booted iOS Simulators appear automatically next to real devices. They are not mirrored until you or your agent opens one, so a simulator running UI tests is left alone.

Do I need Xcode?

For simulators, yes: Xcode provides the simulator. For a real iPhone, setup signs the screen agent with an Apple Development identity on this Mac, and live system touch on iOS 27+ needs a compatible Xcode. Android needs no Xcode.

Can the same agent drive a real iPhone?

Yes, with the same tool names. Run Set Up This iPhone once over USB with Developer Mode on; after that the iPhone works over USB or Wi-Fi.

Does it support Android too?

Yes. Android 11+ phones and Android emulators connect over ADB and use the same MCP tools.

Is it free?

One device at a time is free without signing in. Several devices at once need the iTool yearly membership, ¥99/year or US$26.49/year.

How does the agent pick a device?

Call list_devices, then pass device_id to each tool. Simulators and real devices share one list.

Does the screen leave my Mac?

Not through StupidMirror. The server listens on 127.0.0.1 only. Screenshots your AI client asks for go to that client and follow its data settings.

Device setup guide