Skip to main content
Glama
sully-termux-mcp

sully-termux-mcp

sully-termux-mcp

sully-termux-mcp ist ein Node.js 20+ TypeScript-ESM-Gateway zum Ausführen von MCP-Tools in Termux. Die Produktionsvorgabe ist bewusst klein: Es lauscht nur auf einer Loopback-Adresse, erfordert ein 32-Byte-Bearer-Token und stellt eine separate authentifizierte Admin-API bereit.

Schnellstart

npm ci
npm run build
node dist/cli.js setup
node dist/cli.js start
node dist/cli.js status
node dist/cli.js pair                 # explicit user action; prints both tokens

Die generierte Konfiguration ist ~/.config/sully-mcp/config.json mit Modus 0600; Daten, Job-Ausgaben und das geschwärzte Audit-Log befinden sich unter ~/.local/share/sully-mcp mit Modus 0700. Fügen Sie Pairing-JSON niemals in ein Log oder einen Issue ein.

Für Telefonsteuerungen installieren Sie das Termux:API-Befehls Paket (pkg install termux-api) und installieren Sie die Termux:API-Begleit-App für Android aus derselben Signaturquelle (z. B. beide von F-Droid oder beide von GitHub). Android liefert keine API-Aufrufe, wenn die beiden Pakete aus unterschiedlichen Signaturquellen stammen. Starten Sie das Gateway nach der Installation oder Aktualisierung von Termux:API neu, damit sein Befehlsinventar neu aufgebaut wird.

Der MCP-Endpunkt ist http://127.0.0.1:8765/mcp. Diese Version unterstützt die stabilen sitzungsbasierten Protokolle 2025-11-25 und 2025-06-18 mit initialize, notifications/initialized, tools/list und tools/call. Der Transport 2026-07-28 wird absichtlich nicht beworben, bis seine erforderlichen Routing-Header und das Antwort-Envelope implementiert sind. DELETE /mcp schließt eine 2025-Sitzung.

Related MCP server: Termux MCP Server

Verwaltung

POST /admin/v1 verwendet das Admin-Bearer-Token und akzeptiert { "action": "status", "params": {} }. Zu den Aktionen gehören status, doctor, permissions, capabilities, jobs.list, jobs.output, jobs.cancel, jobs.cleanup, profiles.list, profiles.upsert, profiles.remove, upstreams.list, upstreams.import, upstreams.update, upstreams.remove, gateway.stop, tokens.rotate und pair.revoke. Alle Antworten haben {ok:true,result} oder {ok:false,error}. Geheimnisse werden nur für eine explizite tokens.rotate-Antwort oder den expliziten pair-CLI-Befehl zurückgegeben.

permissions und doctor enthalten eine zentralisierte Termux:API-Checkliste, gruppiert nach Gerät, Kommunikation, Medien, Interaktion und Automatisierung. Die Verfügbarkeit von Befehlen wird beim Start erkannt; der Android-Laufzeitberechtigungsstatus wird als unknown gemeldet, und die Anforderung derselben Signaturquelle für Termux:API ist explizit.

Tools und Grenzen

Zu den integrierten Funktionen gehören begrenzte echo_safe, fs_read, fs_write, fs_list, fs_metadata, fs_find, fs_copy, fs_move, Befehlsprofile, Shell-Jobs, Job-Status/-Ausgabe/-Abbruch/-Bereinigung sowie erkannte Termux:API-Befehle (einschließlich typisierter Standort-, Kamera-, Benachrichtigungs-, Toast-, Zwischenablage-, SMS-, TTS-, Lautstärke- und Taschenlampen-Eingaben). Weniger gebräuchliche API-Befehle legen begrenzte rohe args mit einem Verwendungs-/Hilfehinweis offen; konsultieren Sie die --help-Option des installierten Befehls für genaue Optionen. shell_exec startet immer bash -lc mit shell:false; Befehlsprofile und Stdio-Upstreams verwenden eine ausführbare Datei plus Argumentarray mit shell:false. Jobs überleben Neustarts als interrupted, erfassen höchstens 8 MiB und geben höchstens 64 KiB pro Ausgabeanforderung zurück. Anforderungen sind auf 1 MiB und Antworten auf 4 MiB begrenzt; die Tool-Parallelität beträgt standardmäßig vier.

HTTP-Upstreams müssen HTTPS verwenden oder HTTP auf dem exakten literalen Loopback-Host 127.0.0.1/::1 (keine DNS-Aliase oder Leerzeichen). HTTPS-Ziele, die auf private, link-lokale oder Metadatenbereiche aufgelöst werden, werden abgelehnt. Weiterleitungen, URL-Anmeldeinformationen, Fragmente und nicht in der Whitelist enthaltene Tools werden abgelehnt. HTTP- und Stdio-Upstream-Tools werden mit Präfix versehen (id__tool) und können mit allowedTools, readOnly und prefix eingeschränkt werden.

Termux-Lebenszyklus

Der normale sully-mcp start/restart-Lebenszyklus erwirbt termux-wake-lock, wenn verfügbar, und stop gibt es wieder frei. Installieren Sie termux-boot/sully-termux-mcp als ~/.termux/boot/sully-termux-mcp und machen Sie es ausführbar, um nach einem Neustart zu starten. Die Android-Akkuoptimierung kann Termux trotzdem stoppen; die Anwendung sollte ein nicht verfügbares Gateway als wiederherstellbar behandeln.

Unterstützte CLI-Befehle: setup, start, stop, restart, status, logs, doctor, permissions, pair, update und uninstall --yes.

Release-Integrität

npm run release -- --version 0.2.0 erfordert MCP_RELEASE_ED25519_PRIVATE_KEY und führt einen Build aus, bevor sully-termux-mcp-0.2.0.tar.gz, seine SHA-256, das Manifest und die Ed25519-Signatur geschrieben werden. Der App-Befehl in scripts/install-command.txt lädt das feste GitHub-Release-Archiv, den Hash, das Manifest und die Signatur in ein temporäres Verzeichnis herunter, vergleicht das Archiv mit seinem festgelegten erwarteten Hash, verifiziert die Ed25519-Signatur mit seinem Inline-öffentlichen Schlüssel und führt erst dann das verifizierte scripts/install-local.sh des Archivs aus. Das lokale Installationsprogramm prüft Node 20+, führt npm ci --omit=dev und den Build aus und tauscht einen atomaren versions/<version>/current-Symlink aus, wobei das vorherige aktuelle Ziel bei einem Fehler erhalten bleibt. Es erstellt auch einen echten sully-mcp-Wrapper in Termux's $PREFIX/bin (oder ~/.local/bin) und verwendet niemals eine unverifizierte curl | sh-Pipeline. Der private Signaturschlüssel wird transient über MCP_RELEASE_ED25519_PRIVATE_KEY vom Release-Operator bereitgestellt und niemals committet.

Sicherheitsmodell

Für den lokalen Listener werden nur Loopback-Hosts akzeptiert. MCP- und Admin-Anmeldeinformationen sind unabhängige 64-Hex-Zufallswerte und werden mit einem Vergleich in konstanter Zeit verglichen. Die Konfiguration wird als UTF-8 mit restriktiven Berechtigungen geschrieben. Der Server gibt keine Token von /health, Tool-Listen, normalen Fehlern, Audit-Datensätzen oder Job-Metadaten zurück. Audit-Einträge werden geschwärzt und begrenzt. Tools mit Nebenwirkungen werden niemals automatisch erneut versucht. Destruktive Upstream-Tools müssen vom Aufrufer explizit in die Whitelist aufgenommen werden.

Dieses Repository ist unter der PolyForm Noncommercial License 1.0.0 lizenziert, die von SULLYTEST2 übernommen wurde.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for Termix that enables listing hosts, running commands, reading/writing files, controlling Docker and systemd, managing tunnels, and reading logs.
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to securely interact with an Android device running Termux, executing shell commands with configurable timeouts, smart output truncation, and MCP Streamable HTTP transport for multi-session clients.
      MIT