iphone-mirror-mcp

iphone-mirror-mcp

Permite que cualquier LLM controle un iPhone real.

Un servidor MCP que controla un iPhone físico a través de la aplicación iPhone Mirroring integrada en macOS, y automatiza las pruebas de desarrollo con Xcode — compilar, probar, instalar y ejecutar en simuladores y dispositivos, y luego operar la aplicación en la pantalla reflejada con toques, deslizamientos, escritura y OCR.

Sin jailbreak. Nada instalado en el teléfono. Sin objetivo XCUITest.

run_on_iphone (build → install → launch on the paired iPhone)
   → screenshot / read_screen / tap / paste_text     drive the app on-device
   → wait_for_text / tap with expect / sim_log       assert what the user sees

63 herramientas. Funciona con Claude, GPT, Gemini, modelos locales — cualquier cosa que hable MCP sobre stdio.

---

Inicio rápido

git clone https://github.com/nickatnight96/iphone-mirror-mcp.git
cd iphone-mirror-mcp
./install.sh

El instalador verifica tu máquina, compila un binario de lanzamiento, valida los permisos de principio a fin e imprime la configuración exacta para tu cliente.

Luego, para Claude Code:

claude mcp add --scope user iphone-mirror -- ~/.local/bin/iphone-mirror-mcp

O para cualquier otro cliente MCP:

{
  "mcpServers": {
    "iphone-mirror": {
      "command": "/Users/YOU/.local/bin/iphone-mirror-mcp"
    }
  }
}

Pregúntale a tu modelo:

Toma una captura de pantalla de mi iPhone y dime qué aplicación está abierta.

O descarga el paquete .mcpb desde la última versión si tu cliente instala paquetes MCP y prefieres omitir el toolchain (consulta los inconvenientes — está firmado ad-hoc pero no notarizado).

→ Guía completa de inicio · Configuración por cliente

Requisitos

• macOS 15+ con iPhone Mirroring, emparejado con un iPhone iOS 18+ (cerca, bloqueado, misma cuenta de Apple)
• Xcode — para las herramientas xcode_*, device_* y sim_*
• Permisos de Accesibilidad y Grabación de pantalla, otorgados a la aplicación que inicia el servidor (tu terminal o la aplicación de escritorio que aloja tu cliente) — detalles

Verifica todo de una vez:

iphone-mirror-mcp doctor

Prueba los cuatro permisos, captura un fotograma real y confirma que macOS realmente está entregando entrada sintética — en lugar de solo leer las banderas de permisos. Ejecútalo antes de sospechar de cualquier otra cosa.

Qué puede hacer

Sesión y estado	status, doctor, mirror_launch, mirror_restart
Ver la pantalla	screenshot, annotated_screenshot (cada elemento enmarcado y numerado), read_screen (OCR con centros tocables), find_text, find_image, record_screen
Esperar correctamente	wait_for_text, wait_for_screen_change, scroll_to
Entrada	tap (con verificación expect), double_tap, long_press, swipe, drag, type_text, paste_text (emoji/CJK mediante portapapeles), read_clipboard, press_key, shake, batch
Navegar	home, app_switcher, spotlight, launch_app, open_url
Notificaciones	notifications, notification_click
Xcode	xcode_list, xcode_build, xcode_test, xcresult_attachments
Dispositivos reales	run_on_iphone, devices, device_install, device_launch, device_info, device_apps, device_uninstall
Simuladores	run_on_sim más todo el cinturón de herramientas simctl — push, GPS, concesiones de privacidad, barra de estado, apariencia, registros, medios

→ Referencia completa de herramientas — las 63, con parámetros, generadas desde el catálogo del propio servidor para que no pueda desviarse.

Contrato de coordenadas

Cada x/y es una posición de píxel en la captura de pantalla más reciente, con el origen en la esquina superior izquierda. Al momento de la entrada, se vuelven a consultar los límites de la ventana y el píxel se mapea proporcionalmente dentro de los límites actuales — de modo que una ventana que se movió o redimensionó entre la captura y el toque aún reciba el toque en el lugar correcto.

Documentación

Inicio	Instalación → permisos → primer toque
Conexión de un cliente	Claude Code, Claude Desktop, Cursor, VS Code, Zed, Codex, Windsurf
Referencia de herramientas	Las 63 herramientas y sus parámetros
Recetas	Manejar una aplicación, el bucle de pruebas en el dispositivo, notificaciones, procesamiento por lotes
Solución de problemas	Síntomas → causas → soluciones
Arquitectura	Cómo llega realmente la entrada al teléfono
Limitaciones	Lo que esto genuinamente no puede hacer

Limitaciones conocidas

Probado, no adivinado — la lista completa explica por qué.

• El pellizco y la rotación no se pueden sintetizar. Los gestos del trackpad no viajan por la canalización CGEvent; un toque de evento no ve nada durante un pellizco físico, por lo que no hay nada que reproducir.
• Un teléfono a la vez — el cambio de dispositivo no tiene un menú programable.
• La sesión se pausa cada vez que el teléfono se desbloquea o se levanta. Diseño de Apple; reanudar requiere que esté bloqueado nuevamente.
• Sin árbol de accesibilidad — OCR y coincidencia de plantillas son el modelo de elementos. Face ID, Centro de control y botones de hardware son inalcanzables, y el contenido DRM se captura en negro.

Seguridad

Este servidor puede ver y controlar cualquier iPhone con el que el Mac esté emparejado mientras el espejado esté activo. Trátalo como si le entregaras tu teléfono desbloqueado al modelo. Ejecútalo solo desde clientes en los que confíes.

El teléfono bloquea la sesión en el momento en que se levanta o desbloquea físicamente, lo cual es un interruptor de apagado real. paste_text coloca brevemente texto en el portapapeles del Mac y restaura lo que había; read_clipboard lo lee.

Consulta SECURITY.md para conocer el modelo de confianza y cómo reportar una vulnerabilidad.

Contribuciones

Las incidencias y solicitudes de extracción son bienvenidas — consulta CONTRIBUTING.md.

scripts/run_tests.sh                    # build + unit/protocol tests + CLI smoke
MIRROR_MCP_LIVE=1 scripts/run_tests.sh  # + live tests (real window, capture, input)

Licencia

MIT