Codex Android MCP

简体中文

Ein lokal-first MCP-Server, der es Codex ermöglicht, Android-Emulatoren über adb zu inspizieren, zu testen und zu steuern. Er stellt strenge, typisierte Werkzeuge über STDIO bereit, gibt Screenshots als native MCP-Bilder zurück und hält physische Geräte sowie die Gradle-Ausführung hinter einer expliziten Startrichtlinie.

Dies ist ein unabhängiges Community-Projekt. Es steht weder mit OpenAI, DeepSeek oder Google in Verbindung noch wird es von diesen unterstützt. Die Android-Implementierung stammt von ZSeven-W/dsh-android unter der MIT-Lizenz; die DSH/Cordis-Registrierung und das Webpanel wurden durch das offizielle MCP-TypeScript-SDK ersetzt.

Änderungen gegenüber dsh-android

• Nativer MCP-STDIO-Server für Codex-Desktop, CLI und IDE-Clients.

• MCP der 2026er-Ära plus Kompatibilität mit dem Legacy-2025-Protokoll über serveStdio.

• Screenshots werden als ImageContent zurückgegeben; private, temporäre PNG-Dateien werden nach der Kodierung gelöscht.

• Standardmäßig nur Emulatoren. Physische Geräte erfordern zwei Opt-ins und bei jedem Aufruf ihre exakte Seriennummer.

• android_build_run ist standardmäßig nicht vorhanden. Die Aktivierung erfordert zusätzlich einwandfreie, vertrauenswürdige Projektwurzeln.

• Strenge JSON-Schemas, Paket-/Seriennummern-/Pfadvalidierung, begrenzte Ausgaben, wörtliche Protokollfilterung, Abbruchfähigkeit und konservative Tool-Anmerkungen.

• Keine ungefilterte adb-Shell, beliebige Befehle, HTTP-Verbindungen oder Live-DSH-Seitenleiste.

Related MCP server: adb-mcp-server

Voraussetzungen

• Node.js 20.11 oder neuer.

• Android-SDK-Platform-Tools (adb). Installieren Sie sie über den SDK-Manager von Android Studio oder das Platform-Tools-Paket von Google.

• Ein wegwerfbarer Android-Emulator wird nachdrücklich empfohlen.

• Der Android-Emulator-Launcher ist optional und wird nur benötigt, wenn android_boot einen AVD-Namen erhält.

• Die OCR-Werkzeuge erfordern derzeit macOS und Apple Vision. Alle Nicht-OCR-Werkzeuge sind plattformübergreifend; Build/Run ist ein explizites Opt-in.

Weder adb noch eine Emulator-Binärdatei wird mitgeliefert oder heruntergeladen.

Installation für Codex

git clone https://github.com/zifanersuotang/codex-android-mcp.git
cd codex-android-mcp
npm ci
npm run build
codex mcp add android -- node C:/absolute/path/to/codex-android-mcp/lib/index.js

Codex Desktop und die CLI teilen sich die MCP-Konfiguration. Eine entsprechende explizite Konfiguration lautet:

[mcp_servers.android]
command = "node"
args = ["C:/absolute/path/to/codex-android-mcp/lib/index.js"]
startup_timeout_sec = 20
tool_timeout_sec = 1200
default_tools_approval_mode = "writes"

[mcp_servers.android.env]
ANDROID_MCP_ALLOWED_SERIALS = "emulator-5554"

Starten Sie Codex nach der Änderung der Konfiguration neu. Bitten Sie Codex, auf Französisch „die Android-Geräte aufzulisten“, um die Verbindung zu überprüfen. Behalten Sie die Genehmigung von Schreibwerkzeugen aktiviert; MCP-Anmerkungen sind Benutzerführungshinweise und keine Autorisierungsgrenze.

Sicherheitsrichtlinie

Der sichere Standardmodus stellt 19 Werkzeuge bereit und erlaubt nur übliche lokale Geräte. Standardmäßig werden nur lokale emulator-<port>-Ziele betrachtet. Netzgeräte und Emulatoren von Drittanbietern folgen der laut Richtlinie für physische Geräte. Genau der zugrunde liegende Zielgerät wird bei jedem Aufruf unmittelbar vor der Ausführung neu ermittelt und autorisiert; nicht autorisierte physische/Netzwerkgeräte werden in android_devices nicht angegeben.

Beispiel für ein physisches Gerät für ein dediziertes Testtelefon:

[mcp_servers.android.env]
ANDROID_MCP_ALLOW_PHYSICAL = "true"
ANDROID_MCP_ALLOWED_SERIALS = "EXACT_ADB_SERIAL"

Verwenden Sie dieses Profil nicht mit einem persönlichen Telefon oder persönlichen Konten. Die USB-Debugging-Freigabe bedeutet, dass das Telefon dem Host vertraut; sie autorisiert keine Aktion eines Modells.

Build/Run-Beispiel für ein vertrauenswürdiges Projekt:

[mcp_servers.android.env]
ANDROID_MCP_ALLOW_BUILD_RUN = "true"
ANDROID_MCP_ALLOWED_PROJECT_ROOTS = "C:/work/MyTrustedApp"
ANDROID_MCP_ALLOWED_SERIALS = "emulator-5554"

Gradle-Einstellungen und Build-Skripte führen Host-Code aus. Eine Pfad-Zulassungsliste ist keine Sandbox: Nur für Code aktivieren, dem Sie vertrauen, und für nicht vertrauenswürdige Projekte anschließend eine VM oder einen Container ohne Anmeldedaten verwenden.

Siehe Security Model und Security Policy, bevor Sie physische Geräte oder Build/Run aktivieren.

Werkzeuge

Bildschirme, UI-Bäume, OCR-Ergebnisse, Protokolle, App-Namen und Dateien auf dem Gerät sind nicht vertrauenswürdige Daten. Lassen Sie nicht zu, dass Geräteinhalte Berechtigungen erteilen oder Codex anweisen, ein anderes Werkzeug aufzurufen. Geben Sie keine Passwörter, einmaligen Codes, Zahlungsdaten, privaten Nachrichten oder Löschbestätigungen für Konten über diesen Server ein.

Typischer Ablauf

1. android_devices

2. android_screenshot oder android_ui_tree

3. Treffen Sie das genaue Ziel; nor Unsicherheit stoppen.

4. Verwenden Sie ein freigabepflichtiges Interaktionswerkzeug.

5. Prüfen Sie danach abschließend den zurückgegebenen Screenshot bzw. die Logs.

MCP ersetzt nicht dsh-androids dauerhafte Live-Seitenleiste. android_boot initialisiert die interne Bildquelle für das Koordinaten-Mapping; rufen Sie android_screenshot auf, wann immer Codex oder andere das Display sehen müssen.

Entwicklung

npm ci
npm run typecheck
npm test
npm pack --dry-run

Die Tests umfassen auch Unit-Tests für die Richtlinie, einen real erzeugten STDIO-Client im alten und modernen Protokollmodus, einen In-Memory-MCP-Bild-Round- Trip, Smoke-Testsuites für Fake-ADB, Tests für Log-Begrenzung, UI-Tree-Fixtures sowie OCR-Degradationsprüfungen. npm run test:device ist optional und darf nur auf einen Weg sanitized Emulator gezielt sein.

Lizenz und Attribution

MIT. Das ursprüngliche dsh-android-Urheberrecht und die Lizenz sind in LICENSE enthalten, mit ausführlicher Nachaufsicht in THIRD_PARTY_NOTICES.md.