agent-device MCP Server einrichten

agent-device ist kein gehosteter Dienst, sondern ein lokal installiertes Kommandozeilenwerkzeug, das auch einen MCP-Server bereitstellt. Diese Anleitung zeigt die Schritte von der Installation bis zur ersten Verbindung mit einem KI-Client.

Voraussetzungen

Du brauchst Node.js in Version 22.12 oder neuer (für den Web-Modus Version 24 oder neuer) sowie – je nach Zielplattform – die passende native Toolchain: Xcode mit installiertem iOS-Simulator für iOS und tvOS, das Android SDK mit aktiviertem USB-Debugging und einer autorisierten ADB-Verbindung für Android und Android TV, die HarmonyOS-Toolchain mit HDC für HarmonyOS-Geräte, die Vega-CLI/VDA für die Amazon-Vega-OS-TV-Plattform sowie auf Linux Zugriff auf den AT-SPI-Accessibility-Bus. Auf macOS benötigt der lokale Helfer die Bedienungshilfen-Berechtigung im Systemeinstellungen-Bereich für Datenschutz.

Installation

Installiere das Paket global über npm:

npm install -g agent-device@latest

Führe danach agent-device doctor aus. Der Befehl prüft die lokale Umgebung – etwa installierte SDKs, verbundene Geräte und erteilte Berechtigungen – und zeigt fehlende Voraussetzungen an, bevor du das Werkzeug einem Agenten übergibst. Mit agent-device help workflow erhältst du passende Anleitungen für Debugging, Replay und Profiling, jeweils zur installierten Version passend.

MCP-Server mit einem Client verbinden

Der Befehl agent-device mcp startet den offiziellen stdio-MCP-Server und stellt die installierten CLI-Kommandos als strukturierte Werkzeuge bereit. In Clients wie Claude Code oder Cursor lässt er sich mit folgender Konfiguration eintragen:

{
  "mcpServers": {
    "agent-device": {
      "command": "agent-device",
      "args": ["mcp"]
    }
  }
}

Da der Server über stdio läuft, ist keine zusätzliche Authentifizierung oder URL nötig – der Client startet den Prozess direkt und kommuniziert über Standard-Ein-/Ausgabe. Laut Projekt funktioniert dieselbe Grundkonfiguration analog mit Codex, Windsurf, Cline und Goose.

Erste Session ausführen

Teste die Einrichtung zunächst direkt über die CLI, bevor du einen Agenten daransetzt. Ein einfacher Ablauf mit der eingebauten iOS-Contacts-App sieht so aus:

agent-device open Contacts --platform ios
agent-device snapshot -i
agent-device press @e2 --settle
agent-device screenshot ./beleg.png
agent-device close

snapshot -i zeigt interaktive Elemente mit ihren Referenzen; nach jedem Befehl mit --settle liefert die Ausgabe ein Diff mit neuen, gültigen Referenzen. Referenzen aus älteren Ausgaben werden ungültig – bei Bedarf einfach einen neuen Snapshot anfordern.

Geräte-Zustand prüfen und freigeben

Bei parallel laufenden Agenten oder Worktrees hilft agent-device device status, um zu sehen, welcher Prozess welches Gerät gerade belegt, und agent-device device release --stale, um verwaiste Belegungen ohne laufenden Prozess wieder freizugeben.

Typische Stolperfallen

Ein häufiges Problem ist ein zu alter Node.js-Stand – vor allem der Web-Modus schlägt unter Node.js 22 fehl, weil er Version 24 voraussetzt; agent-device doctor meldet das vorab. Auf Android scheitert die Verbindung oft an nicht autorisiertem USB-Debugging: Prüfe mit einem regulären adb devices, ob das Gerät als „device" und nicht als „unauthorized" erscheint. Auf macOS bricht der lokale Helfer ohne die Bedienungshilfen-Berechtigung ab; die Berechtigung muss in den Systemeinstellungen manuell für das ausführende Terminal- oder Editor-Programm erteilt werden. Verwendest du veraltete Referenzen aus einem älteren Snapshot, meldet der nächste Befehl häufig, dass das Element nicht gefunden wurde – dann hilft ein frischer snapshot-Aufruf.