Oh My Phone Use

Herramientas MCP para el control real de la pantalla de iPhone/iPad mediante un accesorio Bluetooth ESP32 y una Mac, con un modo de firmware separado para llamadas telefónicas.

GitHub

Documentación

Oh My Phone Use

Permite que un agente de IA use un iPhone o iPad real: vea la pantalla, toque, escriba y desplace, y realice llamadas telefónicas que hablen y escuchen en tu nombre.

Una pequeña placa ESP32 es las manos del agente. Actúa como un mouse y teclado Bluetooth para el teléfono y como su unidad de manos libres Bluetooth (kit de coche) para llamadas. Una aplicación en el teléfono comparte la pantalla. Sin jailbreak ni APIs privadas: el teléfono solo ve un accesorio Bluetooth ordinario.

Dos formas de usarlo

Con tu agente (funciona hoy): Claude o cualquier otro cliente MCP se conecta a un servidor MCP en tu Mac y obtiene herramientas de control de pantalla y herramientas de llamadas telefónicas, además de una habilidad que le enseña cómo usarlas de forma segura.
Aplicación de teléfono independiente (planificada): la aplicación en el teléfono maneja el teléfono y realiza llamadas por sí misma, sin un Mac. Consulta Hoja de ruta.

                         ┌─────────────── Mac ───────────────┐
Agent (Claude, …) ──MCP──▶ MCP server ─┬─▶ control server ◀──┼── WebSocket ── phone app (screen sharing)
                         │             └─▶ phone service ────┼── USB serial ──┐            │
                         └───────────────────────────────────┘                │       HTTP over Wi-Fi
                                                                              ▼            ▼
                                                     iPhone / iPad ◀── Bluetooth ── ESP32 board
                                                     (mouse + keyboard, hands-free calls)

Caso de uso 1: Deja que un agente controle tu teléfono

Deja que tu agente vea la pantalla de tu teléfono, toque, escriba y desplace para realizar tareas en sus aplicaciones. El ejemplo a continuación muestra a Codex usando la habilidad Oh My Phone Use para enviar una invitación a cenar a través de la aplicación Mensajes del iPhone.

Codex sending a dinner invitation to John, alongside the iPhone showing the sent message and the ESP32 board

Las imágenes están combinadas para la presentación.

Caso de uso 2: Deja que un agente haga llamadas telefónicas

Dale a tu agente un número de teléfono y una tarea. Puede llamar a través de tu iPhone, hablar y escuchar en tu nombre, mientras sigues la conversación en la página de escucha en vivo. El ejemplo a continuación muestra una llamada preguntando a John a qué hora sale del trabajo, con el iPhone enrutando el audio de la llamada a través del ESP32.

Codex placing a call alongside the live listening page and an iPhone using Oh My Phone Use Audio

Las imágenes están combinadas para la presentación, con el número de teléfono y los detalles personales ocultos. La captura de pantalla muestra una llamada en curso; las transcripciones pueden ser inexactas.

Estado

La estructura del repositorio y las APIs son actualmente inestables y pueden cambiar sin compatibilidad hacia atrás a medida que el proyecto evoluciona.

Capacidad	Estado
Control de pantalla a través de MCP (`get_screen`, `issue_actions`)	Funciona con la compilación de firmware predeterminada; calibración de puntero en la aplicación
Llamadas telefónicas a través de MCP (`phone_*`)	Funciona con la compilación de firmware HFP: marcar o adjuntar, turnos hablados (macOS `say`), transcripción local (whisper.cpp), colgar, resultados guardados
Ambos al mismo tiempo en una placa	Aún no: el ESP32-PICO-V3 carece de RAM para Wi-Fi + HFP + BLE HID juntos
Aplicación independiente	Planificada

Inicio rápido (con tu agente)

Necesitas un ESP32-PICO-KIT-1 (ESP32 clásico), una Mac con ESP-IDF v6.1, Python 3.10+, Node.js 20+, Xcode completo y un equipo de firma de Apple, y un iPhone o iPad con iOS/iPadOS 17 o posterior. Este es el objetivo de implementación de la aplicación, no una afirmación de que cada versión de sistema operativo compatible haya sido probada; consulta las notas de prueba de dispositivos. La ruta de voz de llamadas actual usa macOS say; Linux y Windows no están validados para la configuración completa. El control de pantalla y las llamadas requieren diferentes compilaciones de firmware en la placa actual, como se describe en Estado.

Firmware: compílalo y flashealo, empareja el teléfono por Bluetooth y en un iPhone habilita AssistiveTouch (firmware/README.md):
```
idf.py -C firmware set-target esp32
idf.py -C firmware build
idf.py -C firmware -p /dev/cu.usbserial-XXXXX -b 230400 flash
```

Servidor de control y servidor MCP (el primer inicio crea el secreto del dispositivo de entrada):

npm ci --prefix host/control_server
npm run start:background --prefix host/control_server
npm run calibration:background --prefix host/control_server
npm run mcp:background --prefix host/control_server        # http://127.0.0.1:8780/mcp

Aprovisiona la placa con ese secreto y la red Wi-Fi que usa el teléfono; el script imprime la dirección de la placa (phoneuse.local o una IP):

python3 -m venv .venv && .venv/bin/pip install -r host/tools/requirements.txt
bash host/tools/provision.sh /dev/cu.usbserial-XXXXX "Wi-Fi SSID" "password"

Instala la aplicación (ios/README.md): copia ios/.signing.env.example a ios/.signing.env, establece tu ID de equipo y un ID de paquete único, luego
```
bash ios/scripts/build.sh -allowProvisioningUpdates
xcrun devicectl list devices
bash ios/scripts/install.sh YOUR_DEVICE_ID
```
En la aplicación, ingresa http://phoneuse.local como herramienta de entrada, ws://YOUR_MAC_IP:8765/device como servidor de control, ejecuta la calibración del puntero, luego toca Iniciar sesión y confirma Iniciar transmisión.
Conecta tu agente al servidor MCP y dale la habilidad. Para Claude Code:
```
claude mcp add --transport http oh-my-phone-use http://127.0.0.1:8780/mcp
cp -R skills/oh-my-phone-use ~/.claude/skills/
```
Pídele que haga algo en el teléfono. Verificación rápida sin un agente: node host/control_server/client.js screen guarda una captura de pantalla en host/control_server/.state/.

Las llamadas telefónicas necesitan la compilación de firmware HFP y el servicio de teléfono en la Mac; consulta host/README.md. Cuando un paso no se comporta como se describe, docs/troubleshooting.md enumera los síntomas y sus soluciones.

El servidor MCP y el servidor de control no tienen autenticación: mantenlos en loopback o en una red privada (SECURITY.md). Una llamada llega a una persona real: la habilidad hace que el agente marque solo números que le diste, se presente usando tu nombre preferido o el contexto disponible, explique que las respuestas se transcriben para ti y confirme lo que escuchó.

Estructura del repositorio

Ruta	Qué
`firmware/`	Firmware ESP-IDF: mouse + teclado BLE HID, herramienta de entrada Wi-Fi, unidad de manos libres HFP, pruebas de host
`host/`	Lado Mac: servidor MCP unificado y servidor de control (`host/control_server/`, Node), servicio de teléfono y herramientas seriales (`host/tools/`, Python)
`ios/`	Aplicación iPhone/iPad: compartir pantalla (ReplayKit), sesiones, calibración de puntero, reenvía entrada a la placa
`skills/oh-my-phone-use/`	Habilidad para agentes que usan el servidor MCP
`docs/`	Protocolo HTTP de herramienta de entrada entre la aplicación, el servidor de control y la placa; solución de problemas por síntoma. Los otros protocolos están documentados junto a su implementación: serial en firmware/README.md, servidor de control en host/control_server/PROTOCOL.md
`AGENTS.md`	Convenciones para agentes de codificación y contribuyentes que cambian este repositorio (uno por componente también)

Desarrollo

make -C firmware/test/host test                           # firmware logic, no hardware
npm test --prefix host/control_server                     # control server, MCP server, calibration
.venv/bin/python -m unittest discover -s host/test/phone    # phone service, simulated board
bash ios/scripts/test_relay.sh                            # app relay against the control server
bash ios/scripts/test_frames.sh                           # fresh-frame selection
bash ios/scripts/test_setup.sh                            # setup-step status
bash ios/scripts/test_session_launch.sh                   # Start Session intent hand-off
bash ios/scripts/test_calibration_click.sh                # calibration click policy

Ejecuta estos desde la raíz del repositorio después de instalar las dependencias de Node y Python anteriores. Los scripts de harness Swift requieren una Mac con Apple Silicon ejecutando macOS 14 o posterior, herramientas de línea de comandos de Xcode y Node.js 20+; cuatro scripts actualmente compilan para arm64-apple-macosx14.0. Usan pares simulados y no necesitan teléfono, placa ni credenciales de firma. La suite solo de Node omite la prueba de relay nativa; test_relay.sh compila el harness Swift y ejecuta esa prueba también. Estas pruebas no reemplazan una compilación de la aplicación iOS ni la prueba de aceptación de hardware del firmware.

Hoja de ruta

Llamadas y control de pantalla juntos: un módulo ESP32 con PSRAM (por ejemplo ESP32-WROVER; el ESP32-S3/C3 carece de Bluetooth clásico y no puede hacer HFP) para ejecutar Wi-Fi, HFP y BLE HID a la vez.
Control de llamadas y audio por Wi-Fi: un protocolo de red en la placa para llamadas, reemplazando el enlace serial USB, para que la Mac y la aplicación del teléfono usen la misma API de placa.
Aplicación independiente: el bucle del agente, control de pantalla y llamadas en la aplicación del teléfono, compartiendo vectores de prueba con el compilador de acciones del servidor de control y la calibración.
Migración a Rust: migra el servidor de control Node.js y el servidor MCP en host/control_server/, y las herramientas Python y el servicio de teléfono en host/tools/, a Rust.

Créditos y licencia

El diseño de control de pantalla, la aplicación del teléfono y el servidor de control provienen de jamiepinheiro/ipad_computer_use (MIT), donde un Seeed XIAO RP2040 USB es la herramienta de entrada; este proyecto lo reemplaza con el ESP32 y conserva las partes que necesita. THIRD_PARTY.md enumera los archivos derivados y mantiene el aviso de copyright upstream. La etiqueta upstream-ac07704 marca el commit que importó la instantánea upstream.

Oh My Phone Use se publica bajo la Licencia MIT.