Phone-Eye 📱👁️

Deja que tu agente de IA vea — y opere — un teléfono Android real.

Tu agente de codificación puede leer código, ejecutar comandos y navegar por la documentación. ¿Puede ver la aplicación que está construyendo, en un teléfono real, con píxeles reales? Phone-Eye le da ojos y un dedo.

phone_look("what's on screen, and where is the login button?")
  → "Login button at (540, 1830) — a green 'Sign in' …"
phone_tap(540, 1830)
phone_look("did the next page load?")

Cinco verbos, sin framework: tu agente los compone en el flujo de trabajo que necesite. Funciona con cualquier cliente MCP — Claude Code, Codex, Cursor, dsh y otros.

Por qué

Si construyes o pruebas cualquier cosa que termine en un teléfono, conoces este bucle: el diseño está roto en el dispositivo real, haces capturas de pantalla a mano, describes las pantallas con palabras ("el engranaje, arriba a la derecha, junto a lo de la cuenta") y juegas a decodificar coordenadas entre tu agente y tu teléfono. Phone-Eye cierra ese bucle: el agente itera con el dispositivo de la misma manera que ya itera con tu código.

Dos canales, fusionados:

• Visión — un modelo de visión responde preguntas en lenguaje natural sobre la captura de pantalla en vivo (funciona en lienzos de juegos, imágenes, cualquier cosa que los píxeles puedan mostrar).

• Árbol de UI — volcado de uiautomator para texto y límites exactos cuando el árbol de accesibilidad los tiene.

La visión es conectable. Cualquier servidor MCP que exponga describe_image(path, question) funciona: visión GLM en la nube de serie, o apúntalo a un endpoint local Qwen-VL para que ningún píxel salga de tu LAN.

Related MCP server: scrcpy-mcp

Instalación

Requisitos: Python 3.10+, adb (platform-tools / android-tools) en PATH, un teléfono con depuración USB activada y cualquier servidor MCP de visión.

git clone https://github.com/boheastill/phone-eye
cd phone-eye
pip install -r requirements.txt

# env (defaults shown):
export ANDROID_SERIAL=""                      # empty = first adb device; or 192.168.x.x:5555
export PHONE_EYE_VISION_URL="http://127.0.0.1:8102/mcp"  # your vision MCP

Conéctalo a tu cliente (stdio):

// Claude Code / dsh-mcp-client / any stdio MCP config
{
  "mcpServers": {
    "phone-eye": { "command": "python", "args": ["/path/to/phone-eye/server.py"] }
  }
}

O ejecútalo como un servicio HTTP (streamable-http) detrás de tu propia flota y añade http://<host>:8122/mcp — consulta docs/fleet.md.

Conecta el teléfono (una sola vez)

USB una vez, luego Wi-Fi para siempre:

adb devices                      # USB: accept the debugging prompt on the phone
adb tcpip 5555                   # switch to Wi-Fi mode
adb connect <phone-ip>:5555      # unplug and go

Herramientas

Qué es / qué no es

✔ ojos y manos de agente en un dispositivo Android real, cero instalación en el dispositivo, sin root ✔ visión primero (funciona donde los árboles de UI no ven) con fusión de árbol para precisión ✔ opción de privacidad: apunta la visión a un modelo solo LAN

✘ no es un framework de pruebas (sin DSL/grabador — el agente es la lógica) ✘ no es iOS, no es granjas de dispositivos (todavía) ✘ no es una UI móvil para humanos (eso es un producto diferente)

Estado y hoja de ruta

Fase 1 (ahora): los cinco verbos, un solo dispositivo, visión conectable — verificado de extremo a extremo en hardware real (Redmi K40 Gaming / Android 13). Su truco de fiesta favorito hasta ahora: descubrió un diálogo de autorización de depuración USB en su propia pantalla, leyó los botones y tocó "Permitir" él mismo.

• Fase 2: inicio rápido de visión sin conexión, direccionamiento multi-dispositivo, envoltorios de reintento/verificación

• Todo lo demás: impulsado por solicitudes — abre un issue y sube en la cola.

Licencia

MIT

Preguntas frecuentes

¿Servidor de visión? No tengo uno. Cualquier servidor MCP que exponga describe_image(path, question) funciona. La opción en la nube más rápida es un endpoint de visión GLM; para totalmente sin conexión, un Qwen-VL local (llama.cpp / Ollama compatible con OpenAI + un adaptador de 20 líneas) mantiene cada píxel en tu LAN.

¿Por qué no un plugin nativo de dsh? MCP primero significa que los mismos cinco verbos funcionan en todos los clientes. Los usuarios de dsh pueden conectarlo mediante @deepseek-ai/dsh-mcp-client o dsh plugin add.

Verificado en

Añade el tuyo mediante un PR a esta tabla.