iphone-use

Permite que un agente controle un iPhone real por USB mediante WebDriverAgent: la pantalla como texto, toques basados en instantáneas, escritura y desplazamiento con resultados aplicados/no enviados/desconocidos, wireframes para pantallas que las apps ocultan a la captura, y flujos reproducibles. 21 herramientas, stdio local.

GitHub

265

Documentación

iphone-use

Permite que los agentes de IA usen tu iPhone real.
Claude Code, Codex o cualquier cliente MCP lee la pantalla como texto, toca, escribe y desliza en cualquier aplicación, incluidas las que no tienen API.

English · 简体中文

curl -fsSL https://raw.githubusercontent.com/leeguooooo/iphone-use/main/install.sh | sh

https://github.com/user-attachments/assets/ee298774-bf3e-4fd0-9a08-481b20904f61

_{Demo de 1 minuto, grabaciones de iPhone reales · 中文版}

Por qué iphone-use

Cualquier aplicación, sin necesidad de API. Funciona en Health, aplicaciones bancarias y de pago (incluso las que oscurecen la captura de pantalla), aplicaciones de chat y tu propia aplicación en pruebas.
USB o Wi-Fi. Configura el teléfono una vez con un cable; después se puede controlar por Wi-Fi a través de un túnel cifrado.
También iPhones antiguos. iOS 15 y versiones posteriores, sin actualizar el teléfono.
Rápido. Su propio ejecutor de dispositivos XCTest lee la pantalla en aproximadamente 0,1 s. Un toque que devuelve la pantalla estable tarda aproximadamente 1,9 s (números).
Resultados honestos. Cada acción informa si se aplicó, no se envió o se desconoce, y si es seguro reintentar. Los toques en elementos cubiertos se rechazan, no se dan por hechos.
Flujos reproducibles. Una tarea realizada una vez se convierte en un flujo que se reproduce en una sola llamada, sin modelo ni tokens.
Control remoto para personas también. Controla el teléfono tú mismo desde un navegador u otro iPhone, en la LAN o desde cualquier lugar: una pantalla H.264 en vivo, mouse y teclado, y emparejamiento por código QR. Los agentes y las personas comparten un teléfono sin pisarse (detalles).
Observa al agente en vivo. La pantalla del teléfono se muestra en el panel lateral del host del agente (donde se admiten MCP Apps), en un navegador o en la aplicación iOS.
Nada en el Mac se mueve. Nunca toca la pantalla, el cursor ni el foco del Mac.

Lo que puedes pedir

Open Health and tell me how many steps I walked each day this week.
Find the newest message from Mom in WeChat and read it to me.
Collect every transaction on this bank statement page, all the way to the end.
Write this 2,000-word draft into a new note in Notes.
Run my app's login test on the real phone and tell me which step fails.

El agente encuentra una aplicación por su nombre (launch_app {"app": "Health"}) y escribe texto largo (hasta 20.000 caracteres) en un solo paso. Puede leer una lista a través de páginas y decir si llegó al final.

Cómo funciona

 Claude Code / Codex / any MCP client ──MCP──┐
 scripts and other agents ─────────────HTTP──┤
                                             ▼
                          iphone-use daemon on your Mac ──USB or Wi-Fi──▶ XCTest runner on the iPhone
                                             ▲
 you, in a browser or the iOS app ───────────┘

Un daemon por teléfono se ejecuta en el Mac. Lee la pantalla como un árbol de accesibilidad (texto, no píxeles), envía toques y escritura a través de un pequeño ejecutor XCTest que instala en el teléfono, y verifica que la pantalla se haya estabilizado antes de responder. Los agentes y las personas pasan por el mismo daemon, y uno de ellos tiene el teléfono a la vez.

Instalación

Necesitas

Un Mac con macOS 15 o posterior, y Xcode iniciado sesión con un Apple ID (uno gratuito funciona).
Un iPhone con iOS 15 o posterior y el Modo Desarrollador activado (Configuración → Privacidad y Seguridad → Modo Desarrollador).
Un cable USB para la primera configuración. Conecta el iPhone y desbloquéalo antes de instalar.

El instalador luego configura el teléfono y muestra a un agente abriendo Configuración y leyéndola. Registra el servidor MCP con Claude Code y Codex, y con Cursor y Claude Desktop cuando están instalados (IPHONE_USE_NO_CLIENT_SETUP=1 omite esos dos), y abre la página de control en tu navegador con un inicio de sesión único, por lo que no hay contraseña que copiar. Si falta algo, dice qué y cómo solucionarlo.

iphone-use status    # is the phone ready for agents?
iphone-use doctor    # what is missing, and how to fix it
iphone-use setup     # set the phone up again (after a new iPhone or Xcode)
iphone-use try       # a harmless check: open Settings, read the screen, go Home
iphone-use login     # sign a browser in again, with a QR code for the iPhone
iphone-use upgrade   # update everything
~/.iphone-use/uninstall.sh --dry-run   # what uninstalling would remove (drop --dry-run to do it)

O pídele a tu agente que lo instale

Pega esto en Codex o Claude Code en el Mac al que está conectado el iPhone:

Install iphone-use (https://github.com/leeguooooo/iphone-use) on this Mac so you can drive my iPhone.
1. Run: curl -fsSL https://raw.githubusercontent.com/leeguooooo/iphone-use/main/install.sh | sh
2. Run `iphone-use doctor`. Fix what it reports that can be fixed from the terminal, and run
   `iphone-use setup` when it tells you to.
3. Some steps only I can do: signing in to an Apple ID in Xcode, tapping Trust on the iPhone,
   turning on Developer Mode, unlocking the phone. For those, stop, tell me exactly what to do,
   and wait until I say it is done. Never ask me for a password or a code.
4. Run `iphone-use doctor` again until nothing is missing, then `iphone-use try`.
5. If the phone_* tools are not loaded in this chat yet, tell me to start a new chat.

Plugins de Codex y Claude Code

Cada uno agrega la habilidad y el servidor MCP; aún necesitan la instalación anterior:

codex plugin marketplace add leeguooooo/iphone-use && codex plugin add iphone-use@iphone-use

En Claude Code:

/plugin marketplace add leeguooooo/iphone-use
/plugin install iphone-use@iphone-use

Control remoto para personas

El mismo daemon que sirve a los agentes te permite controlar el teléfono tú mismo:

Desde un navegador. La pantalla en vivo llega codificada como H.264 en el teléfono: resolución nativa a aproximadamente 50 fps en la LAN, y un modo más ligero para enlaces lentos. Haz clic para tocar, arrastra para deslizar, mantén presionado para una pulsación larga, desplázate con la rueda o el trackpad. Escribe directamente en el teléfono con tu método de entrada, y ⌘V pega. El panel Controles lista los elementos de la pantalla para que puedas tocar por etiqueta, y el panel Flujo registra lo que haces como un flujo reproducible. La página sigue el idioma de tu navegador (inglés o chino), con un interruptor en la barra lateral.
Desde otro iPhone. La aplicación iOS nativa (objetivo de implementación mínimo iOS 15) se empareja escaneando un código QR en la página del Mac, sin dirección ni contraseña que escribir. Reproduce la pantalla con el decodificador de hardware y cambia entre tus teléfonos.
Pantallas ocultas de la captura. Las aplicaciones bancarias y de pago oscurecen la captura de pantalla; allí ves un wireframe en vivo de los elementos de la pantalla en lugar de una imagen en blanco, y aún puedes tocar a través de él.
Desde cualquier lugar. Accede al Mac a través de un proxy inverso HTTPS autenticado o una VPN como Tailscale, y controla el teléfono desde fuera de tu red (notas de seguridad).
Sin colisiones. Un teléfono tiene un propietario a la vez. Mientras tú tienes el control, un agente espera o se le dice quién tiene el teléfono, y viceversa.

Nada en el Mac se mueve mientras lo haces: ninguna ventana toma el foco y el cursor permanece en su lugar.

Úsalo desde un agente

Un daemon en tu Mac controla el teléfono y ofrece el mismo control en tres formas:

un servidor MCP para Claude Code, Codex, Claude Desktop, Cursor y otros clientes MCP;
una API HTTP para agentes y scripts (/agent/*);
una página web y una aplicación iOS nativa para personas (control remoto).

El instalador registra el servidor MCP con Claude Code, Codex, Cursor y Claude Desktop cuando están presentes (IPHONE_USE_NO_CLIENT_SETUP=1 deja Cursor y Claude Desktop en paz). Cualquier otro cliente MCP solo necesita el comando; en este Mac el servidor encuentra el daemon y su token por sí mismo:

{
  "mcpServers": {
    "iphone-use": {
      "command": "/Users/YOU/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp"
    }
  }
}

Configuración para Cursor, VS Code, Claude Desktop, Gemini CLI, opencode, Windsurf

Usa la ruta absoluta (reemplaza YOU) y fusiona la entrada en el archivo; conserva los servidores que ya están allí.

Cursor: ~/.cursor/mcp.json (o .cursor/mcp.json en un proyecto), el bloque mcpServers anterior.
Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json, el bloque mcpServers anterior; sal y vuelve a abrir la aplicación.
Gemini CLI: ~/.gemini/settings.json (o .gemini/settings.json en un proyecto), el bloque mcpServers anterior.
Windsurf / Devin Desktop: ~/.codeium/windsurf/mcp_config.json (builds más nuevos: ~/.config/devin/mcp_config.json), el bloque mcpServers anterior.

VS Code / Copilot: .vscode/mcp.json en un espacio de trabajo, o MCP: Open User Configuration para cada espacio de trabajo. La clave es servers:

{
  "servers": {
    "iphone-use": {
      "type": "stdio",
      "command": "/Users/YOU/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp"
    }
  }
}

opencode: ~/.config/opencode/opencode.json (o opencode.json en un proyecto). La clave es mcp y el comando es un array:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "iphone-use": {
      "type": "local",
      "command": ["/Users/YOU/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp"],
      "enabled": true
    }
  }
}

O llama a la API HTTP directamente:

AUTH="Authorization: Bearer $TOKEN"; CTL="X-Phone-Control: 1"
curl -s -H "$AUTH" $HOST/agent/elements                     # the screen as text + a snapshot token
curl -s -H "$AUTH" -H "$CTL" -X POST "$HOST/agent/input?return=delta" \
  -d '{"type":"tap","element":7,"snapshot":"…"}'            # tap, then what changed (~2 s)

Para desarrolladores de aplicaciones y testers, las mismas herramientas también leen los registros del teléfono y los informes de fallos, graban la pantalla en MP4, instalan un build (.ipa, .app o un enlace https), establecen una ubicación simulada y mantienen notas por aplicación que los agentes leen cuando entran en la aplicación. IPHONE_USE_MCP_TOOLS=readonly expone solo las herramientas que leen, y iphone-use-mcp --listen 127.0.0.1:PORT sirve MCP sobre HTTP. Un listener de loopback solo es accesible desde el mismo Mac; para un cliente en otra máquina, colócalo detrás de un túnel autenticado, o escucha en otra dirección con IPHONE_USE_MCP_TOKEN configurado (es obligatorio fuera de loopback).

¿No tienes un teléfono a mano? Mientras desarrollas, controla un Simulador de iOS de la misma manera (vista previa, necesita Xcode): iphone-use simulator start "iPhone 16 Pro" construye e inicia todo, luego apunta al agente con claude mcp add iphone-sim -e IPHONE_USE_INSTANCE=sim -- iphone-use-mcp. Consulta Simuladores.

Consulta las herramientas MCP y la referencia de la API de agente.

Seguridad y privacidad

Los secretos se quedan contigo. Para inicios de sesión, códigos de acceso y Face ID, el agente se detiene y te pide que termines en el teléfono. Nunca pide la contraseña ni el código.
Límites que el agente no puede eludir con conversación. El daemon rechaza aplicaciones que bloqueas (IPHONE_USE_BLOCKED_APPS, por ejemplo Wallet, Passwords) y limita las acciones por tarea (IPHONE_USE_MAX_ACTIONS), sin importar lo que diga el prompt del agente (detalles).
Ves lo que hace. La página web muestra cada acción sobre la pantalla en vivo en palabras simples, por ejemplo Tapped “Wi-Fi”. El texto escrito nunca se guarda, solo su longitud.
Local por defecto. El daemon escucha en 127.0.0.1:44321 detrás de una contraseña, y el ejecutor en el teléfono solo acepta solicitudes firmadas con un token por lanzamiento. La ruta LAN de iOS 15/16 no está cifrada (seguridad).
Sin telemetría. Este build no envía datos de uso (telemetría · política de privacidad).

Flujos: haz una tarea una vez, reprodúcela sin modelo

Las tareas que repites se guardan como flujos: scripts revisados por aplicación que se reproducen sin modelo, por lo que no cuestan tokens. El registro oficial es leeguooooo/iphone-use-flows. Graba un flujo en el panel Flujo del navegador y publícalo allí con un PR.

Los agentes encuentran flujos por sí mismos: cuando uno entra en una aplicación, la respuesta lista los flujos de esa aplicación. Después de que un agente hace una tarea de varios pasos en una aplicación que no tiene ninguno, pregunta si quiere guardar la tarea como un flujo; el daemon ya ha registrado los pasos como un borrador. El daemon mantiene el registro actualizado por sí mismo (IPHONE_USE_FLOWS_NO_AUTO_UPDATE=1 lo desactiva, IPHONE_USE_FLOWS_NO_SUGGEST=1 silencia las sugerencias de guardado).

MCP=~/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp
$MCP flow update                            # sync the registry (sha256-checked)
$MCP flow list                              # what is available
$MCP flow run health/export-all-zh-cn       # replay one; failures say which step and why
$MCP flow draft --out my-task.json          # what you just did on the phone, as a draft flow

Los flujos también crean suites de pruebas reejecutables ($MCP test suite.yaml, con un código de salida listo para CI) y ejecuciones programadas que el daemon inicia en una línea cron ($MCP schedule add): consulta Pruebas y ejecuciones programadas.

Velocidad

iphone-use controla el teléfono a través de su propio ejecutor XCTest (runner/). Habla la API HTTP de WebDriverAgent y está construido para la velocidad:

Lee la pantalla con una sola instantánea de accesibilidad de un conjunto de atributos fijo, en lugar de recorrer el árbol de elementos atributo por atributo.
Sintetiza toques directamente y no espera a que la aplicación esté inactiva antes de actuar; el daemon verifica después que la pantalla se haya estabilizado.
Es una aplicación pequeña con un servidor HTTP integrado y una transmisión MJPEG; no hay dependencias adicionales en el teléfono.

Medido en el mismo iPhone 13 por USB, contra agent-device (octubre de 2026):

	ejecutor iphone-use	agent-device
Leer la pantalla (árbol de accesibilidad)	0,08–0,135 s	~0,7 s
Tocar y luego esperar a que la pantalla se estabilice	1,0 s	2,8–3,3 s

A través de la API completa del agente, un toque por etiqueta que devuelve el cambio estabilizado tarda aproximadamente 1,9 s en un iPhone 17 Pro Max; la versión basada en WebDriverAgent tardó 4,2 s. La vista en vivo transmite a 27–28 fps. Cada teléfono tiene su propio daemon y ejecutor, por lo que dos teléfonos controlados al mismo tiempo funcionan tan rápido como cualquiera de ellos solo.

Más

Guía completa: navegador y aplicación iOS, flujos y el registro de flujos, Wi-Fi e iOS 15/16, ciclo de vida, configuración, seguridad, desarrollo.
Referencia de la API de agente · Herramientas MCP · Arquitectura · Errores comunes de configuración del dispositivo · Ejecutor de dispositivos · Privacidad
Guía de producto: instalación, configuración de MCP, flujos y cómo se compara.
Problemas e ideas: Problemas de GitHub.

Licencia

PolyForm Shield 1.0.0. Este proyecto es de código fuente disponible. Se permiten el uso, la modificación y la distribución no competitivos sujetos a la licencia; está prohibido usar el software para proporcionar un producto o servicio competidor, incluido uno gratuito. Consulta alcance de la licencia y avisos de terceros.

La familia `*-use`

CLIs pequeños y componibles que le dan a un agente de IA acceso directo a una cosa real. Misma forma en todas partes: curl … install.sh | sh para instalar, JSON en stdout y una skill complementaria que enseña a tu agente a manejarlo — el README de cada repositorio explica cómo instalar su skill, ya que la forma correcta varía según el proyecto y la versión.

Repo	Le da a tu agente
chrome-use	Un navegador real — sesiones iniciadas, formularios, scraping, capturas de pantalla
mail-use	Correo electrónico — leer, buscar, enviar, clasificar en Gmail / QQ / 163 / cualquier IMAP
wechat-use	WeChat en macOS — enviar mensajes, consultar contactos e historial
discord-use	Discord — mensajes, canales, foros, webhooks (solo REST, Rust)
cookie-use	Muchas cuentas iniciadas por sitio — capturar, cambiar, aplicar sesiones
profile-use	Tu perfil personal, de forma segura — completar formularios de registro / KYC / pago
bitwarden-use	Bitwarden / Vaultwarden — inicio de sesión headless con passkey (FIDO2)
chatgpt-use	Tu suscripción de ChatGPT como backend de agente de codificación — sin clave de API
computer-use	El escritorio de macOS en sí
pixcake-use	Sondeo de solo lectura de PixCake — snapshot / diff / inspección de SQLite

Autor

Creado por 郭立 (Guo Li / leeguoo) — leeguoo.com · GitHub · X · más herramientas en la familia *-use.

iphone-use

Documentación

iphone-use

Por qué iphone-use

Lo que puedes pedir

Cómo funciona

Instalación

O pídele a tu agente que lo instale

Plugins de Codex y Claude Code

Control remoto para personas

Úsalo desde un agente

Seguridad y privacidad

Flujos: haz una tarea una vez, reprodúcela sin modelo

Velocidad

Más

Licencia

La familia *-use

Autor

La familia `*-use`