Phone-Eye 📱👁️

Lass deinen KI-Agenten sehen – und ein echtes Android-Telefon bedienen.

Dein Coding-Agent kann Code lesen, Befehle ausführen und Dokumentation durchsuchen. Kann er die App, die er baut, auf einem echten Telefon mit echten Pixeln sehen? Phone-Eye gibt ihm Augen und einen Finger.

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?")

Fünf Verben, kein Framework: Dein Agent setzt sie zu jedem Workflow zusammen, den er braucht. Funktioniert mit jedem MCP-Client – Claude Code, Codex, Cursor, dsh und anderen.

Warum

Wenn du etwas baust oder testest, das auf einem Telefon landet, kennst du diese Schleife: Das Layout ist auf dem echten Gerät kaputt, du machst Screenshots von Hand, beschreibst Bildschirme in Worten („das Zahnrad, oben rechts, neben dem Konto-Ding“) und spielst Koordinaten-Dolmetscher zwischen deinem Agenten und deinem Telefon. Phone-Eye schließt diese Schleife – der Agent arbeitet mit dem Gerät so, wie er bereits mit deiner Codebasis arbeitet.

Zwei Kanäle, verschmolzen:

• Vision – ein Vision-Modell beantwortet Fragen in natürlicher Sprache zum Live-Screenshot (funktioniert auf Spiel-Canvas, Bildern, allem, was Pixel zeigen können).

• UI-Baum – uiautomator-Dump für exakten Text und Grenzen, wenn der Accessibility-Baum sie hat.

Vision ist austauschbar. Jeder MCP-Server, der describe_image(path, question) bereitstellt, funktioniert – Cloud-GLM-Vision sofort einsatzbereit, oder richte es auf einen lokalen Qwen-VL-Endpunkt, damit kein Pixel dein LAN verlässt.

Related MCP server: scrcpy-mcp

Installation

Voraussetzungen: Python 3.10+, adb (platform-tools / android-tools) im PATH, ein Telefon mit aktiviertem USB-Debugging und ein beliebiger MCP-Vision-Server.

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

Binde es in deinen Client ein (stdio):

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

Oder betreibe es als HTTP-Dienst (streamable-http) hinter deiner eigenen Flotte und füge http://<host>:8122/mcp hinzu – siehe docs/fleet.md.

Telefon verbinden (einmalig)

Einmal per USB, dann für immer per WLAN:

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

Werkzeuge

Was es ist / nicht ist

✔ Agentenaugen + Hände auf einem echten Android-Gerät, keine Installation auf dem Gerät, kein Root ✔ Vision-first (funktioniert, wo UI-Bäume nicht sehen können) mit Baum-Verschmelzung für Präzision ✔ Datenschutzoption: Vision auf ein LAN-only-Modell richten

✘ kein Test-Framework (kein DSL/Recorder – der Agent ist die Logik) ✘ kein iOS, keine Gerätefarmen (noch nicht) ✘ keine mobile UI für Menschen (das ist ein anderes Produkt)

Status & Fahrplan

Phase 1 (jetzt): die fünf Verben, einzelnes Gerät, austauschbare Vision – Ende-zu-Ende auf echter Hardware verifiziert (Redmi K40 Gaming / Android 13). Sein bisheriger Lieblingstrick: Es hat einen USB-Debugging-Autorisierungsdialog auf dem eigenen Bildschirm entdeckt, die Schaltflächen gelesen und selbst auf „Erlauben“ getippt.

• Phase 2: Offline-Vision-Schnellstart, Multi-Geräte-Adressierung, Retry/Verify-Wrapper

• Alles andere: anfragegesteuert – öffne ein Issue und es rückt in der Warteschlange auf.

Lizenz

MIT

FAQ

Vision-Server? Ich habe keinen. Jeder MCP-Server, der describe_image(path, question) bereitstellt, funktioniert. Die schnellste Cloud-Option ist ein GLM-Vision-Endpunkt; für vollständig offline hält ein lokales Qwen-VL (llama.cpp / Ollama OpenAI-kompatibel + ein 20-Zeilen-Adapter) jeden Pixel in deinem LAN.

Warum kein dsh-natives Plugin? MCP-first bedeutet, dass dieselben fünf Verben in jedem Client funktionieren. dsh-Nutzer können es über @deepseek-ai/dsh-mcp-client oder dsh plugin add einbinden.

Verifiziert auf

Füge deines per PR zu dieser Tabelle hinzu.