ChatGPT iPhone Bridge

Controla Mobile Safari en un iPhone real conectado por USB desde ChatGPT a través de OpenAI Secure MCP Tunnel y Appium MCP.

Este es un puente local experimental y no oficial. No abre ningún puerto de entrada público y no expone Appium directamente a Internet.

Arquitectura

ChatGPT
  -> OpenAI Secure MCP Tunnel
  -> tunnel-client on your Mac
  -> Appium MCP over stdio
  -> XCUITest / WebDriverAgent
  -> USB-connected iPhone
  -> Mobile Safari

Related MCP server: Simulator MCP

Requisitos

• macOS con Xcode 16 o superior

• Node.js 22 o superior

• un iPhone emparejado con el Modo desarrollador activado

• Ajustes -> Apps -> Safari -> Avanzado -> Inspector web activado en el iPhone

• Ajustes -> Apps -> Safari -> Avanzado -> Automatización remota activado en el iPhone

• un Apple ID/Equipo personal en Xcode

• un perfil de desarrollo válido cuyo bundle ID sea * o termine en .xctrunner

• un OpenAI Secure MCP Tunnel asociado a la organización de destino de Platform y al espacio de trabajo de ChatGPT

• una clave de API de runtime con permisos Tunnels Read + Use

• acceso a la app de ChatGPT en modo desarrollador

Documentación oficial del túnel: OpenAI Secure MCP Tunnel.

1. Arranque

bash scripts/bootstrap-local.sh

El repositorio fija appium-mcp en la versión 1.92.7. El arranque valida la cadena de herramientas, instala el paquete exacto, ejecuta un handshake directo de MCP, enumera los dispositivos de Xcode e informa de la disponibilidad de firma.

Si falta la firma, añade el Apple ID en Xcode -> Ajustes -> Cuentas y selecciona el Equipo personal. A continuación, genera el perfil exacto del runner de WDA desde el proyecto incluido:

IOS_DEVICE_UDID=<connected UDID> \
DEVELOPMENT_TEAM=<Apple team ID> \
bash scripts/prepare-ios-signing.sh

El bundle ID del perfil de runner predeterminado es com.kapunakap.chatgptiphonebridge.WebDriverAgentRunner.xctrunner. Sobrescribe la base con WDA_BUNDLE_ID_BASE cuando sea necesario; omite el sufijo .xctrunner porque Xcode lo añade al runner.

A continuación, vuelve a ejecutarlo:

bash scripts/ios-signing-status.sh

Antes del primer lanzamiento de WDA, confía en la app de desarrollador en el iPhone en Ajustes -> General -> VPN y gestión de dispositivos.

Si la creación de la sesión de Safari informa de que el depurador remoto no respondió, vuelve a comprobar tanto Inspector web como Automatización remota, descarta cualquier modal de Safari o pantalla de primer uso y mantén el teléfono desbloqueado. about:blank debe funcionar antes de probar una URL de aplicación.

2. Aprovisionar un túnel dedicado

Crea un túnel en OpenAI Platform y asócialo al espacio de trabajo de ChatGPT que lo utilizará. Guarda su clave de runtime fuera de este repositorio:

mkdir -p "$HOME/.config/chatgpt-iphone-bridge"
chmod 700 "$HOME/.config/chatgpt-iphone-bridge"
umask 077
cat > "$HOME/.config/chatgpt-iphone-bridge/runtime-api-key"
# paste the runtime key, then press Ctrl-D
chmod 600 "$HOME/.config/chatgpt-iphone-bridge/runtime-api-key"

Nunca pases la clave en bruto como argumento de línea de comandos ni hagas commit de ella.

3. Conectar

CONTROL_PLANE_TUNNEL_ID=tunnel_... bash scripts/connect-tunnel.sh

Valores predeterminados:

• alias del túnel: local-iphone

• clave de runtime: ~/.config/chatgpt-iphone-bridge/runtime-api-key

• capturas de pantalla: ~/Library/Application Support/chatgpt-iphone-bridge/screenshots

4. Crear la app de ChatGPT

En los Plugins del modo desarrollador de ChatGPT:

1. Crea una app llamada Local iPhone.

2. Elige Tunnel.

3. Selecciona el túnel de iPhone dedicado.

4. Elige No Auth para la propia app MCP.

La comprobación de salud local no equivale a la aceptación en el entorno alojado. Confirma que ChatGPT puede descubrir y llamar a las herramientas de Appium antes de confiar en el puente.

5. Preparar el dispositivo real

Pide a ChatGPT que use Local iPhone en este orden:

1. Llama a select_device con platform=ios y iosDeviceType=real.

2. Llama a appium_prepare_ios_real_device sin un UUID de perfil.

3. Elige un perfil devuelto marcado como recommendedForWda=true.

4. Vuelve a llamar a la herramienta de preparación con ese UUID de perfil.

5. Crea una sesión con platform=ios y una cadena JSON de capacidades que contenga:

{
  "browserName": "Safari",
  "appium:usePreinstalledWDA": true,
  "appium:prebuiltWDAPath": "<returned path>",
  "appium:wdaLaunchTimeout": 30000,
  "appium:initialDeeplinkUrl": "<exact test URL>"
}

Usa los valores exactos devueltos. Tras una selección o preparación correcta del dispositivo real, el puente inyecta el UDID del iPhone solo en tiempo de ejecución cuando una sesión real de WDA omite appium:udid. Un UDID explícito se conserva. No guardes IDs de dispositivo, IDs de equipo, UUID de perfil ni rutas de WDA en este repositorio.

Operaciones

npm test
bash scripts/status.sh
bash scripts/stop.sh

Para una llamada local única a una herramienta MCP, pasa los argumentos por stdin para que los valores específicos del dispositivo no aparezcan en los argumentos del proceso:

printf '%s\n' '{"platform":"ios","iosDeviceType":"real"}' \
  | npm run tool -- select_device

Elimina la sesión activa de Appium antes de detener el túnel cuando sea posible.

Seguridad de la sesión

Este puente compone el servidor predeterminado a través de la API de plugins appium-mcp/core compatible, sin añadir ni reemplazar herramientas de Appium. Mantiene la interfaz original de 31 herramientas y añade solo salvaguardas en tiempo de ejecución:

• una selección de dispositivo real permanece disponible para la creación posterior de sesiones de WDA;

• los UDID explícitos de iPhone se conservan;

• las capacidades de sesión de simulador y de no iOS no se modifican;

• la creación concurrente o duplicada de sesiones propiedad de Appium falla de forma segura.

Los identificadores de dispositivo permanecen solo en memoria y nunca se escriben en el repositorio.

Seguridad

Este puente puede controlar un teléfono real desbloqueado y cualquier sesión de Safari iniciada. Lee SECURITY.md antes de conectarlo.

Licencia

MIT. Consulta LICENSE.