MCP Android Agent

Dieses Projekt bietet einen MCP-Server (Model Context Protocol) zur Automatisierung von Android-Geräten mit uiautomator2 . Er lässt sich problemlos in KI-Agenten wie GitHub Copilot Chat, Claude oder Open Interpreter integrieren, um Android-Geräte über natürliche Sprache zu steuern.

Schnelle Demo

Anforderungen

Python 3.13 oder höher
Android Debug Bridge (adb) installiert und im PATH
Verbundenes Android-Gerät mit aktiviertem USB-Debugging
uiautomator2- kompatibles Android-Gerät

Merkmale

Starten, Stoppen und Verwalten von Apps nach Paketnamen
Installierte Apps und aktuelle Vordergrund-App abrufen
Tippen, wischen, scrollen, ziehen und UI-Interaktionen durchführen
Erhalten Sie Geräteinformationen, Bildschirmauflösung, Akkustatus und mehr
Erfassen Sie Screenshots oder letzte Toast-Nachrichten
Bildschirm programmgesteuert entsperren, aktivieren oder in den Ruhezustand versetzen
App-Daten löschen und auf Aktivitäten warten
Enthält einen Gesundheitscheck und adb Diagnosetool

Anwendungsfälle

Perfekt für:

KI-Agenten, die mit realen Geräten interagieren müssen
Remote-Gerätesteuerungs-Setups
Automatisierte QA-Tools
Android-Bot-Frameworks
UI-Tests und Automatisierung
Geräteverwaltung und -überwachung

Installation

1. Klonen Sie das Repo

git clone https://github.com/nim444/mcp-android.git
cd mcp-android

2. Virtuelle Umgebung erstellen und aktivieren

# Using uv (https://github.com/astral-sh/uv)
uv venv
source .venv/bin/activate  # On Windows: .venv\\Scripts\\activate

3. Abhängigkeiten installieren

uv pip install

Ausführen des Servers

Option 1: Verwendung von uvicorn (empfohlen)

uvicorn server:app --factory --host 0.0.0.0 --port 8000

Option 2: Verwenden von MCP stdio (für die Integration von KI-Agenten)

python server.py

Verwendung

Zur Nutzung dieses Servers ist ein MCP-Client erforderlich. Die Claude Desktop-App ist ein Beispiel für einen MCP-Client. So nutzen Sie diesen Server mit Claude Desktop:

Suchen Sie Ihre Claude Desktop-Konfigurationsdatei

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Fügen Sie die Android MCP-Serverkonfiguration zum Abschnitt mcpServers hinzu

{
  "mcpServers": {
    "mcp-android": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "cd /path/to/mcp-adb && source .venv/bin/activate && python -m server"
      ]
    }
  }
}

Ersetzen Sie /path/to/mcp-adb durch den absoluten Pfad zum geklonten Repository. Beispiel: /Users/username/Projects/mcp-adb

Verwendung mit VS Code

Sie können diesen MCP-Server auch im Agentenmodus von VS Code verwenden (erfordert VS Code 1.99 oder neuer). So richten Sie ihn ein:

Erstellen Sie eine .vscode/mcp.json -Datei in Ihrem Arbeitsbereich:

{
  "servers": {
    "mcp-android": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "cd /path/to/mcp-adb && source .venv/bin/activate && python -m server"
      ]
    }
  }
}

Ersetzen Sie /path/to/mcp-adb durch den absoluten Pfad, unter dem Sie dieses Repository geklont haben.

Nachdem Sie die Konfiguration hinzugefügt haben, können Sie den Server wie folgt verwalten:

Befehlspalette → MCP: List Servers zum Anzeigen und Verwalten konfigurierter Server
Befehlspalette → MCP: Start Server , um den Server zu starten
Die Tools des Servers werden im Agentenmodus-Chat von VS Code verfügbar sein

UI-Inspektor

Das Projekt umfasst Unterstützung für uiauto.dev, ein leistungsstarkes UI-Inspektionstool zum Anzeigen und Analysieren der Schnittstellenstruktur Ihres Geräts.

Installieren Sie den UI-Inspektor:

uv pip install uiautodev

Starten Sie den Inspektor:

uiauto.dev

Öffnen Sie Ihren Browser und navigieren Sie zu https://uiauto.dev

Verfügbare MCP-Tools

Werkzeugname	Beschreibung
`mcp_health`	Überprüfen Sie, ob der MCP-Server ordnungsgemäß läuft
`connect_device`	Stellen Sie eine Verbindung zu einem Android-Gerät her und erhalten Sie grundlegende Informationen
`get_installed_apps`	Listen Sie alle installierten Apps mit Versions- und Paketinformationen auf
`get_current_app`	Erhalten Sie Informationen über die App, die gerade im Vordergrund ist
`start_app`	Starten Sie eine App anhand ihres Paketnamens
`stop_app`	Stoppen einer App anhand ihres Paketnamens
`stop_all_apps`	Stoppen Sie alle derzeit laufenden Apps
`screen_on`	Schalten Sie den Bildschirm ein
`screen_off`	Schalten Sie den Bildschirm aus
`get_device_info`	Erhalten Sie detaillierte Geräteinformationen: Seriennummer, Auflösung, Akku usw.
`press_key`	Simulieren Sie das Drücken einer Hardwaretaste (z. B. `home` , `back` , `menu` usw.).
`unlock_screen`	Bildschirm entsperren (einschalten und ggf. wischen)
`check_adb`	Überprüfen Sie, ob ADB installiert ist, und listen Sie die verbundenen Geräte auf
`wait_for_screen_on`	Asynchron warten bis der Bildschirm eingeschaltet wird
`click`	Tippen Sie auf ein Element nach `text` , `resourceId` oder `description`
`long_click`	Führen Sie einen langen Klick auf ein Element aus
`send_text`	Geben Sie Text in das aktuell fokussierte Feld ein (optional vorher löschen)
`get_element_info`	Erhalten Sie Informationen zu UI-Elementen (Text, Grenzen, anklickbar usw.).
`swipe`	Wischen Sie von einer Koordinate zur anderen
`wait_for_element`	Warten Sie, bis ein Element auf dem Bildschirm erscheint
`screenshot`	Machen und speichern Sie einen Screenshot vom Gerät
`scroll_to`	Scrollen Sie, bis ein bestimmtes Element sichtbar wird
`drag`	Ziehen Sie ein Element an eine bestimmte Stelle auf dem Bildschirm
`get_toast`	Holen Sie sich die letzte Toast-Nachricht, die auf dem Bildschirm angezeigt wird
`clear_app_data`	Benutzerdaten/Cache einer bestimmten App löschen
`wait_activity`	Warten Sie, bis eine bestimmte Aktivität angezeigt wird
`dump_hierarchy`	Dumpen Sie die UI-Hierarchie des aktuellen Bildschirms als XML

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert – Einzelheiten finden Sie in der Datei LICENSE .

MCP Android Agent

Integrations