A lightweight HTTP server that runs inside Termux on Android, exposing shell execution and device capabilities as a streaming API. Built for AI agents, LLM tool-calling, and automation scripts.
AI Agent --> POST /run {"cmd": "ls -la"} --> Termux-MCP --> Termux Shell
|
<-- chunked streaming output -+
Powerful MCP server for Termux — let AI agents run shell commands on your Android device in real time.
Estrelas
43
Ferramentas
—
Disponibilidade
—
Two commands — which do I run?
Command
What it is
termux-mcp
REST API daemon on :8080 (this README's endpoints)
termux-native-mcp
Native MCP server (Model Context Protocol, spec 2025-06-18) for MCP clients: RikkaHub, desktop AI apps (Cursor, ...)
Both install together via pkg install termux-mcp and run as separate
processes — starting termux-native-mcp never touches the REST daemon's
port, state or behavior.
termux-mcp # REST API on 127.0.0.1:8080
termux-native-mcp # native MCP, Streamable HTTP on 127.0.0.1:8081
termux-native-mcp --stdio # native MCP over stdin/stdout (desktop clients)
pip install . registers the command globally, so the cd is only needed for
the install itself. Without it, python -m termux_mcp only works from inside
the clone.
Command timeout in seconds. 0 = no timeout (default) — long operations like pkg upgrade run until they finish. Set a positive value to re-enable the watchdog kill.
TERMUX_MCP_AUTH
off
Authentication is off by default (loopback only). Set on to require a token: it is read from TERMUX_MCP_AUTH_TOKEN, or generated into ~/.termux-mcp/token (mode 0600) on first start.
TERMUX_MCP_AUTH_TOKEN
(generated)
Use this token instead of the generated one
TERMUX_MCP_CONFIG_DIR
~/.termux-mcp
Token, capability tokens, policy.json, event logs
TERMUX_MCP_LOG_EVENTS
1
0 stops the JSONL event log (logs/events.jsonl)
TERMUX_MCP_MAX_OUTPUT
20000
Max streamed output bytes per command. Output beyond this is drained (process keeps running) but not sent; a truncation marker is appended. Keeps LLM tool results small and token-efficient.
The app needs no setup: termux-mcp listens on loopback and the app connects straight to it. If you
want a token instead, set TERMUX_MCP_AUTH=on before starting the server — termux-mcp token prints
it for clients that speak Authorization: Bearer ..., and termux-mcp token --rotate replaces it
immediately. When binding to a non-loopback address, authentication cannot be switched off.
Endpoints
Shell & Filesystem
Endpoint
Method
Parameters
Description
/run
POST
cmd (string, required)
Execute a shell command with streaming output. The working directory is process-wide and shared between clients over HTTP — chain cd x && cmd for isolation.
/ls
POST
path (string, default .), detailed (bool)
List directory contents
/read
POST
path (string, required)
Read a file (first 500 lines)
/write
POST
path, content
Write content to a file via base64 encoding
/mkdir
POST
path
Create directory (mkdir -p)
/delete
POST
path, recursive (bool), confirmed (bool)
Delete file or directory. Requires confirmation.
/search
POST
path, pattern (or query/name)
Find files by name pattern
/cancel
POST
Cancel currently running command
System Monitor & Management
Endpoint
Method
Parameters
Description
/system-info
POST
Live CPU%, RAM, disk, temperature, uptime as JSON
/process-list
POST
limit (int, default 20)
List running processes sorted by CPU usage
/process-kill
POST
pid (int), signal (int, default 15)
Terminate a process by PID
/health
POST
Full diagnostic: core packages, Termux:API, storage, network, permissions
Cron Scheduler
Endpoint
Method
Parameters
Description
/cron-add
POST
schedule, command, label
Add a cron job. Schedule format: 0 3 * * * for daily at 3am.
/cron-list
POST
List all cron jobs
/cron-remove
POST
label (optional)
Remove cron jobs matching a label, or all if no label given
Backup, Restore & Cloud Sync
Endpoint
Method
Parameters
Description
/backup
POST
target (home/packages/configs), output, include
Create a tar.gz backup of home, packages, or configs
Create backups and provide cloud upload instructions
/changes_list
POST
format (json/text), limit, since, task_id
Every file write, delete and trash the safety layer recorded, newest first, with a revertable flag
/undo
POST
path, limit, since, task_id, confirmed
Put files back to their earlier contents from the snapshots. Needs confirmed: true, since an undo is itself undone by taking a snapshot first
Code & Files
Endpoint
Method
Parameters
Description
/diff
POST
file, file2 (optional)
Show diff between files, or file stats for a single file
/patch
POST
file, patch
Apply a diff patch to a file
Device & Sensors
Endpoint
Method
Parameters
Description
/battery
POST
Battery status via termux-battery-status
/location
POST
provider (gps/network, default gps)
GPS coordinates via termux-location
/wifi-info
POST
WiFi connection details
/wifi-scan
POST
Scan nearby WiFi networks
/camera-photo
POST
camera_id (0/1), output
Take a photo
/camera-info
POST
List available cameras
/screenshot
POST
output
Take a screenshot
/sensor
POST
sensor, limit
Read sensor data
/fingerprint
POST
Fingerprint authentication
/vibrate
POST
duration_ms
Vibrate the device
/torch
POST
state (on/off)
Toggle flashlight
/brightness
POST
level
Get/set screen brightness
/volume
POST
stream, level
Get/set volume
Communication
Endpoint
Method
Parameters
Description
/notify
POST
title, content, priority, id
Send an Android notification
/notify-remove
POST
id
Remove a notification
/sms-send
POST
number, text
Send an SMS
/sms-inbox
POST
limit
Read SMS inbox
/tts-speak
POST
text, rate, pitch
Text-to-speech
/speech-to-text
POST
Speech recognition
/toast
POST
text
Show an Android toast
/dialog
POST
title, message
Show a confirmation dialog
/share
POST
text or file
Share via Android intent
/clipboard-get
POST
Read clipboard
/clipboard-set
POST
text
Set clipboard
/call
POST
number
Initiate a phone call
/contacts
POST
List contacts
/list-apps
POST
List installed apps
Network
Endpoint
Method
Parameters
Description
/open-url
POST
url
Open URL in browser
/download
POST
url, description, title
Download a file
/public-ip
POST
Get public IP address
/weather
POST
city
Weather via wttr.in
/speedtest
POST
Internet speed test
/web-server
POST
action (start/stop/status), port, directory
Start a Python HTTP server
Media
Endpoint
Method
Parameters
Description
/image-process
POST
action, input, output, width, height
Image operations via ImageMagick
/video-process
POST
action, input, output, crf, start, duration
Video operations via FFmpeg
/text-extract
POST
input, lang
OCR via Tesseract
/qrcode
POST
text, output
Generate QR code
/scan-barcode
POST
camera_id, output
Scan barcode via camera
/screen-record
POST
output, action (start/stop)
Screen recording
/microphone-record
POST
output, limit_seconds, action
Microphone recording
/wallpaper
POST
file, lockscreen
Set wallpaper
Doctor & Playbooks
Endpoint
Method
Parameters
Description
/do
POST
text, dry_run, confirmed, format
Do what the user asked, in their own words, when the phone already knows how. Matches their words to a playbook and fills its values — free, no model. If it is not known, nothing runs
/doctor
POST
check, fix, confirmed, task_id, format (text/json)
Check this install for the things that break everyday work — missing tools, unlinked storage, a stuck package manager, no network. Reports and names the fix; with fix: true it applies each failing check's repair (its requirements first), then re-checks. Every repair command goes through the same risk gate, snapshots and journal as any other
/capsule
POST
action (export/preview/import), playbook, path, sign, signer, confirmed, overwrite, format
Move a saved task between phones as one file: a checksum, a manifest of what it does and would install, and an SSH signature when the phone has a key. A preview shows all of it; nothing installs without confirmed: true
/harvest
POST
steps, title, values, phrases, playbook, overwrite, format
Save what was just done as a task the phone can repeat with no model: the values in the commands become slots. Validated before it lands in ~/termuxGPT/playbooks/
/playbooks
POST
playbook, run, dry_run, with, confirmed, task_id, undo, format
List the library, read one, run one, or undo a run. A run meets its requirements first, verifies each step, and writes a record — so the whole thing undoes as one unit
Playbooks are declarative, one JSON file each, and validated when they load:
phrases, typed slots, preconditions, steps with a verification, and the line
to say afterwards. The doctor's checks are the same objects — a check is a
probe with a fix, and a playbook's requires names a check. Ten ship with
the package (update and upgrade, install anything, clone a repo, storage
setup, check space, find what is eating it, clear the package cache, battery,
wifi, an SSH key); harvest adds more, saved under ~/termuxGPT/playbooks/
and loaded alongside the shipped ones.
Smart Tools
Endpoint
Method
Parameters
Description
/smart-install
POST
packages, manager, dry_run
Intelligent package install with conflict detection
Ask the user to approve one exact action on the device — their fingerprint, or a dialog when no fingerprint is enrolled. An approved action runs once, within 3 minutes
/ask
POST
widget, title, hint, values, multiline, format
Ask the user for input with a native Android dialog: text, number, radio, sheet, spinner, checkbox, date, time or speech. values are the choices; commas inside one are fine, backslashes are not
/tools
GET
Full OpenAI-format tool schemas for all tools (function-calling ready)
/catalog
GET
Compact tool catalog: {name, desc, params, category} per tool — small enough to embed in an LLM system prompt or a use_tool meta-tool
Only six entries are listed in tools/list (run_digest, out_read, context_pack, batch,
tool_search, smart). The other ~40 are reached with smart {tool, params} after tool_search
returns their schema, so the per-request tool list stays small. Every one is also a REST endpoint
(POST /<tool>) and a WebSocket tool; native MCP results carry structuredContent.
Every shell call made by a smart tool has a hard timeout and runs in its own process group, so a hung
termux-* command is killed with all of its children instead of blocking the connection.
0.13 — hardened kernel, learning, autonomy, power tools
One execution kernel./run, WebSocket run, MCP run, run_digest and every shell-backed
endpoint go through kernel.gate() — capability scope → policy.json → dangerous tier → warning tier
(with one-shot device approvals) — and share one watchdog (TERMUX_MCP_TIMEOUT, termux-* helpers
capped at 25 s, process groups via start_new_session). Transport-parity tests keep all four
answering the same way. GET /metrics (and the metrics tool) shows per-tool p50/p95 latency, error
rates, error codes and FixGraph success rates; each call is also a line in ~/.termux-mcp/logs/events.jsonl.
Learn once, run forever.
Tool
What it does
learn_propose / learn_save
Compact a finished task (failed and exploratory steps dropped, values → slots, verify kept) into a playbook that intent/do replays with no model
semantic intent
A trigram + word TF-IDF phrase bank (no dependencies) catches paraphrases: "no room left on my phone" → storage_clean
fix_learn / fix_share
A fix that worked becomes a candidate; after 2 successes FixGraph returns it. Export/import with a checksum (imports start untrusted)
plan_cache_get / plan_cache_put / plan_replay
The same request on the same device replays its last good plan (plan_checked first)
prompt_pack
Only the rules/tools a task type needs instead of one big system prompt
Autonomy with guard-rails.
Tool
What it does
goal_run
plan_check → steps in one transaction → one known fix per failure → verify → commit, or roll back and return a decision. Budget {steps, minutes, fixes}
policy_get / policy_set
deny_paths, allow_paths, deny_tools, network, pip: venv_only, sandbox_unknown_scripts. Tightening is free; loosening needs an on-device approval (approve action=policy_set)
cap_issue / cap_list / cap_revoke
Scoped, expiring cap_… tokens (tools, paths, read-only) for external MCP clients, enforced on REST, WebSocket, PTY and native MCP. Only their hash is stored
dry_run: true
On every write tool: what would happen and what the kernel would decide, nothing executed
timeline / undo_task
Changes grouped by task; undo any past task, with a warning when later tasks touched the same files
Power tools:venv_ensure, node_ensure, proot_ensure/proot_run, cron_ensure, tunnel
(time-limited public URL), web_fetch (readable text / CSS selector), db_query (SQLite or CSV),
log_watch (reactor log_match), file_find (indexed), backup_incremental (dedup + verify +
restore; encrypted via restic), clipboard_pipe, share_to, media_convert (ffmpeg presets with
progress), ssh_hosts/ssh_run.
All of them are reached through smart {tool, params} / tool_search, so tools/list stays at six
entries.
Streaming Output
The /run endpoint and most tool endpoints use HTTP chunked transfer encoding. Output is sent line-by-line as the command produces it. Clients should read the response as a stream and process each chunk as it arrives.
For long-running commands, a watchdog thread enforces the timeout. Package install commands automatically receive -y flags and DEBIAN_FRONTEND=noninteractive to prevent prompts.
Security
Command injection. Every parameter interpolated into a shell command is
quoted with shell_quote, and every numeric parameter is validated by
require_number/require_int — a value that is not a number is rejected,
not passed through. Parameters embedded in double-quoted echo arguments
are quoted as whole strings, since double quotes still permit $(...).
Risk gate. Commands are assessed before execution. The DANGEROUS tier
(e.g. rm -rf /, mkfs., writes to /dev/, chmod -R 777) is refused on
every shell-backed endpoint — the check lives in the shared executor, so a
new endpoint cannot forget it. The WARNING tier (package removals,
recursive deletes) requires an explicit confirmed: true on /run, or an
approval for that exact command taken from the device with /approve —
which costs the user a fingerprint instead of a tap.
Sensitive writes./write and /patch can edit anything outside
/dev, /proc and /sys — that is the point of them — but paths that
grant persistence require confirmation: ~/.ssh/, ~/.bashrc,
~/.profile, ~/.termux/ (including boot/), and anything under
$PREFIX. These are an SSH backdoor, code run on shell start, and code run
at device boot respectively.
Authentication. Off by default, and the server refuses to start unless it
is on when HOST is non-loopback. With TERMUX_MCP_AUTH=on, every endpoint
requires a Bearer token — POST, GET (except /ping, which the client's
connectivity probe needs before it holds a token), and the WebSocket, which
accepts the token via the Authorization header or a ?token= query
parameter.
Capability tokens (cap_…) are accepted everywhere with their scope
enforced; they never get a raw PTY unless they name terminal_open.
Network. A request carrying an Origin header is rejected unless that
origin is allowlisted, so a page open on the device cannot reach the server
by resolving its own hostname to loopback. Requests with no Origin (the
app, curl, stdio clients) are unaffected.
Request body size is capped at 5 MB; WebSocket frames at 8 MB.
Request bodies are not logged — only their size.
Each WebSocket connection keeps its own cd state. Over HTTP the working
directory is process-wide and shared between clients, so one caller's
cd affects the next; chain cd x && cmd if you need isolation.
License
GNU Affero General Public License v3.0 (AGPL-3.0)
Copyleft — anyone who distributes a modified version, or hosts it as a
service (SaaS), must release their changes under the same license.
Note: versions up to 0.8.3 were released under the MIT License; those
releases keep their MIT terms. AGPL-3.0 applies from 0.8.4 onward.
T
Termux
termuxgpt·43 estrelas·
Powerful MCP server for Termux — let AI agents run shell commands on your Android device in real time.
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Termux?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Termux precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte Termux usa?
Termux roda localmente via stdio.
Quando Termux foi verificado pela última vez?
Última verificação: 2026-10-27. Powerful MCP server for Termux — let AI agents run shell commands on your Android device in real time.