Turn on the MCP server
Open Settings → MCP and enable the local MCP server. It listens only on http://127.0.0.1:<port>/mcp.
MCP SERVER
Give Claude Code a real iPhone or Android.
StupidMirror exposes connected devices through an authenticated MCP server on this Mac. It embeds no model and needs no model API key: it hands the device to the agent you already use.
Connect an MCP client
Codex users can also click Connect Codex for the bundled plugin. For Claude Code and other clients, use the generated configuration.
Pick your client
In Advanced connection settings · Other AI clients, choose Codex or Claude Code in the connection guide.
Copy the configuration
Copy the generated configuration or command into that client. It includes the endpoint, bearer authentication and a 240-second tool timeout for slow first-time control setup.
Ask the agent
Keep StupidMirror open and try: “List my connected devices, start mirroring my iPhone, and highlight the visible clickable elements without tapping them.”
Observe, act, verify
Connect
list_devices, show_screen and connect_control discover the target and prepare the sessions it needs.
Observe
observe_screen and find_any_element read a live frame with local OCR, and request accessibility only when needed.
Act
tap_text, tap_element, replace_text and swipe target observed content or an explicit gesture.
Verify
wait_for, assert_screen and observe_screen check the resulting state on the device.
Guide without touching
highlight_clickable_elements and highlight_elements draw targets on the Mac mirror without sending input.
Apps and recordings
install_app installs an .app, .ipa or .apk build; open_url opens deep links; start_recording saves the mirror as an .mp4 of up to 10 minutes.
Local server, your AI client's rules
Capture, playback and OCR run on this Mac, and StupidMirror does not upload mirrored content to a model provider on its own. An AI client connected over MCP receives the screenshots and tool results it asks for, and its own data settings apply. Rotating the bearer token invalidates the previous credential.
Questions from agent authors
Does StupidMirror need a model API key?
No. It embeds no model. Your MCP client brings the model; StupidMirror provides the device tools.
Which clients work?
Codex through the bundled plugin, Claude Code through the generated command, and other MCP clients through the generated configuration with bearer authentication.
Why is the first action slow?
First-time control setup can take a while, so the generated configuration sets a 240-second tool timeout.
How do I target one of several devices?
Pass device_id. Call list_devices first to see the identifiers.
How should an agent edit iOS text fields?
After focusing a field, use replace_text or clear_text directly, and type_text to append. Accessibility snapshots can disturb a focused field, and replacement verifies the resulting value.
Which languages does OCR read?
Apple Vision OCR defaults to Chinese and English, offers fast and accurate modes, and runs on demand outside the capture path.