Termux API & PRoot-Distro Ubuntu mit MCP-Server

Dieses Projekt stellt ein Bootstrap-Skript bereit, um Ubuntu unter proot-distro auf Android über Termux zu installieren, Android-System-APIs darin zu binden und einen Python-basierten Model Context Protocol (MCP)-Server zu starten.

Mit diesem MCP-Server, der auf Ihrem Telefon läuft, können Sie jedem externen KI-Client (wie Cursor, Claude Desktop, Windsurf oder benutzerdefinierten HTTP-Agenten) die volle Kontrolle über die Hardware Ihres Android-Geräts gewähren, Sensoren auslesen, Kommunikation abrufen und Shell-Befehle ausführen.

Schnellstart (Drei-Schritte-Einrichtung)

Schritt 1: Ubuntu auf Termux installieren und konfigurieren

Führen Sie diesen Befehl in Ihrem nativen Termux-Terminal aus, um Ubuntu zu installieren, zu konfigurieren und sich anzumelden. (Dies lädt zuerst das Skript herunter, damit stdin an Ihrer Tastatur bleibt und Sie korrekt angemeldet werden.)

curl -sLO https://raw.githubusercontent.com/AbuZar-Ansarii/Termux-MCP/main/install_ubuntu.sh && chmod +x install_ubuntu.sh && ./install_ubuntu.sh

Sobald dieses Skript abgeschlossen ist, meldet es Sie automatisch bei Ubuntu an und bringt Sie zur Eingabeaufforderung: root@localhost:~#

Schritt 2: MCP klonen und einrichten (innerhalb von Ubuntu)

Sobald Sie sich im Ubuntu-Container (root@localhost:~#) befinden, kopieren Sie diesen Befehl und fügen Sie ihn ein, um das Repository zu klonen, das Setup-Skript auszuführen und die virtuelle Umgebung zu aktivieren:

git clone https://github.com/AbuZar-Ansarii/Termux-MCP.git && cd Termux-MCP && chmod +x setup_mcp.sh && ./setup_mcp.sh && source venv/bin/activate

(Das Anhängen der Anweisung source venv/bin/activate stellt sicher, dass sie im Kontext Ihrer übergeordneten Shell ausgeführt wird. Nach Abschluss befinden Sie sich in der aktivierten virtuellen Umgebung an der Eingabeaufforderung: (venv)root@localhost:~/Termux-MCP#.)

Schritt 3: MCP-Server ausführen

Führen Sie den Server direkt in der aktiven virtuellen Umgebung aus:

python termux_mcp.py --transport sse

Sobald der Server läuft, erkennt er die IP-Adresse Ihres Telefons und zeigt eine kopierbare Verbindungs-URL an (z. B. http://192.168.1.15:8000/sse), die Sie direkt in Ihren KI-Client einfügen können!

Zukünftiger Schnellbefehl

Für zukünftige Ausführungen (aus nativem Termux, ohne manuelles Anmelden und Aktivieren) können Sie den Server mit einem einzigen Befehl starten:

proot-distro login ubuntu -- bash /root/run_mcp.sh

Related MCP server: android-shizuku-mcp

Warum PRoot-Distro Ubuntu?

Das Ausführen einer Linux-Distribution wie Ubuntu innerhalb von Termux mit proot-distro bietet mehrere wichtige Vorteile:

1. Glibc (GNU C Library)-Kompatibilität: Android und natives Termux verwenden Bionic libc, das sich in Pfaden und Standards unterscheidet. Viele kompilierte Pakete, Datenbank-Binärdateien, Node-Module und Python-Bibliotheken benötigen standardmäßiges glibc, um ohne Kompilierungsfehler zu laufen. PRoot-Distro Ubuntu bietet eine standardmäßige glibc-Umgebung.

2. Paketvielfalt & Ökosystem: Ubuntu gibt Ihnen Zugriff auf die riesigen apt-Paketarchive. Wenn Ihr Workflow standardmäßige Linux-Server-Tools, Desktop-Pakete oder kompilierte Dienste erfordert, ist die Ausführung in Ubuntu rootfs weitaus robuster als das Patchen für natives Android/Bionic.

3. Isolation & Sandbox: Die Entwicklung innerhalb von PRoot Ubuntu hält Ihr Host-Termux-Dateisystem sauber und modular. Wenn etwas kaputt geht oder Sie einen Neuanfang wünschen, können Sie den Distributionscontainer einfach zurücksetzen, ohne Ihre Termux-Konfigurationen zu verlieren.

4. Hardware-API-Brücke: Unser Bootstrap-Skript bindet den nativen Termux-Ordner $PREFIX in Ubuntu ein. Das bedeutet, Sie erhalten das Beste aus beiden Welten: eine vollwertige Ubuntu-Linux-Umgebung, die dennoch direkten Befehlszeilenzugriff auf Android-APIs (wie Kamera, Toast, Standort und Sensoren) hat.

Funktionen (MCP-Tools)

Der MCP-Server stellt eine vollständige Reihe von Tools zur Steuerung Ihres Telefons bereit:

• System & Hardware:

  • get_battery_status: Batteriestand, Gesundheit, Temperatur und Ladestatus des Geräts lesen.

  • toggle_torch: Taschenlampe/Torch EIN oder AUS schalten.

  • set_screen_brightness: Bildschirmhelligkeit ändern (0-255).

  • get_volume_info & set_volume: Lautstärkepegel für Alarm, Musik, Klingelton, Anruf, System und Benachrichtigungen lesen oder setzen.

• Kommunikation:

  • list_contacts: Alle auf dem Telefon gespeicherten Kontaktnamen und Telefonnummern auflisten.

  • get_call_log: Den letzten Anrufverlauf abrufen.

  • list_sms & send_sms: Posteingang/gesendete Nachrichten auflisten und neue Textnachrichten senden.

• Sensoren & Netzwerk:

  • get_location: Präzise GPS- oder netzwerkbasierte Koordinaten abrufen.

  • get_wifi_connection_info: WLAN-Verbindungsmetadaten abrufen (SSID, BSSID, IP, Verbindungsgeschwindigkeit).

  • get_telephony_device_info: Telefonie-Anbieter, Signalstärke und Netzwerktyp abfragen.

• Medien & Fotos:

  • take_photo: Fotos mit der Front- oder Rückkamera aufnehmen und auf einem Dateipfad auf dem Gerät speichern.

  • tts_speak: Gesprochene Sprache mit Google TTS synthetisieren.

• Benutzerinteraktion & Zwischenablage:

  • show_toast: Temporäre Toast-Benachrichtigungen auf dem Telefonbildschirm anzeigen.

  • vibrate_phone: Das Gerät für eine festgelegte Dauer vibrieren lassen.

  • clipboard_get & clipboard_set: Android-Zwischenablage lesen und schreiben.

  • show_notification: Standard-Android-Benachrichtigungen anzeigen.

  • prompt_user_dialog: Einen interaktiven Texteingabe-Dialog auf dem Telefon anzeigen, mit dem Sie eine Antwort an den KI-Client zurückschreiben können.

  • share_text: Text direkt in das native Android-Share-Sheet teilen.

• Beliebige Ausführung:

  • execute_command: Beliebige Shell-Befehle direkt im nativen Termux-Host ausführen.

Detaillierte Schritt-für-Schritt-Installation

Schritt 1: Termux & Termux:API auf Android installieren

1. Installieren Sie die Termux-App und die Termux:API-App.

   • Erforderlich: Installieren Sie beide Apps von F-Droid (mischen Sie nicht F-Droid- und Play-Store-Versionen, da diese nicht zusammen signieren/binden).

2. Gehen Sie zu Android-Einstellungen -> Apps -> Termux:API -> Berechtigungen:

   • Erteilen Sie Kamera, Standort, SMS, Kontakte und Speicher-Berechtigungen.

3. Deaktivieren Sie die Batterieoptimierung für Termux und Termux:API, um zu verhindern, dass Android die Hintergrunddienste beendet.

Schritt 2: Setup-Skript ausführen

Öffnen Sie Termux und fügen Sie den folgenden Befehl ein:

curl -sLO https://raw.githubusercontent.com/AbuZar-Ansarii/Termux-MCP/main/install_ubuntu.sh && chmod +x install_ubuntu.sh && ./install_ubuntu.sh

Schritt 3: MCP-Server-Setup ausführen

Sobald Sie sich im Ubuntu-Container befinden:

git clone https://github.com/AbuZar-Ansarii/Termux-MCP.git && cd Termux-MCP && chmod +x setup_mcp.sh && ./setup_mcp.sh && source venv/bin/activate

Schritt 4: Server starten

In der aktivierten Umgebung ((venv)root@localhost:~/Termux-MCP#):

python termux_mcp.py --transport sse

Das Terminal gibt die Verbindungs-URL aus:

==================================================================
   🤖 Termux MCP Server Running in SSE Mode
==================================================================
   👉 SSE Connect URL: http://192.168.1.15:8000/sse
   👉 Messages URL:    http://192.168.1.15:8000/messages/
==================================================================

Schritt 5: Mit Ihrem KI-Client verbinden

Sie können jeden Client verbinden, der MCP über Server-Sent Events (SSE) unterstützt.

Cursor verbinden:

1. Öffnen Sie Cursor-Einstellungen -> Features -> MCP.

2. Klicken Sie auf + Add New MCP Server.

3. Geben Sie ein:

   • Name: termux-mcp

   • Typ: SSE

   • URL: http://YOUR_PHONE_IP:8000/sse (Kopieren Sie die vom Server ausgegebene 'SSE Connect URL')

4. Klicken Sie auf Speichern.

Claude Desktop verbinden (Alternative Stdio über SSH)

Wenn Sie lokale Stdio-Befehle über SSH leiten möchten, finden Sie in Option B in der Repository-Dokumentation Anweisungen zum Einrichten von OpenSSH-Schlüsseln und zum Konfigurieren Ihrer lokalen %APPDATA%\Claude\claude_desktop_config.json.

Fehlerbehebung

• Tool-Aufruf hängt: Wenn ein Tool-Aufruf (wie get_location oder take_photo) hängt, überprüfen Sie, ob die Termux:API-App in den Android-Einstellungen Berechtigungen erhalten hat und der Batteriesparmodus deaktiviert ist.

• Verbindung abgelehnt: Stellen Sie sicher, dass PC und Telefon mit demselben WLAN-Netzwerk verbunden sind und der Server läuft.

• Termux-Hintergrundausführung: Android kann Termux-Prozesse aussetzen, wenn der Bildschirm gesperrt ist. Ziehen Sie die Android-Benachrichtigungsleiste herunter und stellen Sie sicher, dass Termux "1 Sitzung" mit aktiviertem "Acquire wake lock" anzeigt, damit es im Hintergrund weiterläuft.