Termux-MCP
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 -+
Installation
pkg update && pkg install python git -y
git clone https://github.com/termuxgpt/termux-mcp
cd termux-mcp
python -m termux_mcp
Or via the package repository:
curl -fSL https://termux-mcp.pages.dev/add-repo.sh | bash
pkg install termux-mcp
termux-mcp
Quick Test
curl http://localhost:8080/ping
curl -X POST http://localhost:8080/run -H "Content-Type: application/json" -d '{"cmd": "ls ~"}'
Configuration
| Variable |
Default |
Description |
TERMUX_MCP_PORT |
8080 |
HTTP listen port |
TERMUX_MCP_HOST |
127.0.0.1 |
Bind address. Use 127.0.0.1 for local-only. |
TERMUX_MCP_TIMEOUT |
0 |
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_TOKEN |
(none) |
Bearer token for authentication |
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. |
Set TERMUX_MCP_AUTH_TOKEN to a value 16+ characters long to require authentication on all endpoints. When binding to a non-loopback address, authentication is mandatory.
Endpoints
Shell & Filesystem
| Endpoint |
Method |
Parameters |
Description |
/run |
POST |
cmd (string, required) |
Execute a shell command with streaming output. Maintains persistent cd state across requests. |
/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 |
/restore |
POST |
file, target |
Restore from a backup file |
/cloud-sync |
POST |
action (backup/restore/list), target, output, file |
Create backups and provide cloud upload instructions |
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 |
Smart Tools
| Endpoint |
Method |
Parameters |
Description |
/smart-install |
POST |
packages, manager, dry_run |
Intelligent package install with conflict detection |
/diagnose |
POST |
intent (python/pip/node/git/storage/packages/all) |
Run diagnostics for a specific tool |
/pkg-smart |
POST |
intent, install |
Intent-based package discovery (60+ mappings) |
/dev-env |
POST |
intent, name |
One-click development environment setup |
/profile |
POST |
profile, dry_run |
Pre-configured Termux profiles (dev, python, web, hacker, etc.) |
/optimize |
POST |
|
Performance analysis and recommendations |
/error-explain |
POST |
error, command |
Gather context to help AI explain errors |
/permission-fix |
POST |
target |
Diagnose and fix permission issues |
/storage-audit |
POST |
|
Find large files and suggest cleanup |
/deps-tree |
POST |
package |
Show package dependency tree |
/config-fix |
POST |
config |
Check Termux configuration issues |
/review |
POST |
file |
Static analysis (syntax check, linting) |
/log-analyze |
POST |
file |
Extract errors and warnings from log files |
/script-gen |
POST |
description, type, output |
Generate shell or Python script templates |
/regex |
POST |
pattern, test |
Test regex patterns with grep |
/db-design |
POST |
schema, output |
Create SQLite database from schema description |
/db-query |
POST |
database, query |
Execute SQLite query |
/translate |
POST |
text, target_lang, source_lang |
Text translation |
/tutorial |
POST |
topic |
Interactive Termux learning guide |
Git Operations
| Endpoint |
Method |
Parameters |
Description |
/git-op |
POST |
action (clone/status/log/diff/pull/push/branch), url, directory, repo_dir |
General git operations |
/git-smart |
POST |
action (diff-summary/log-recent/suggest-commit/fix-conflict), repo_dir |
AI-friendly smart git operations |
SSH, Services & Migration
| Endpoint |
Method |
Parameters |
Description |
/ssh-wizard |
POST |
action (setup/status/stop) |
Full SSH server setup with key generation |
/service-guard |
POST |
action, name, cmd |
Background service management |
/history-insight |
POST |
file, limit |
Analyze shell usage patterns, suggest aliases |
/quick-cmd |
POST |
action, name, cmd |
Alias and shortcut management |
/port-manage |
POST |
action, port |
Network port visibility |
/migrate |
POST |
action (backup/restore/preview), output, file |
Full Termux environment migration |
Other
| Endpoint |
Method |
Parameters |
Description |
/ping |
GET |
|
Health check |
/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 |
/env |
GET |
|
Environment info (cwd, home, pid) |
/explain |
POST |
cmd |
Explain what a shell command does |
/telephony-deviceinfo |
POST |
|
Device telephony info |
/telephony-cellinfo |
POST |
|
Cell tower info |
/infrared |
POST |
frequency, pattern |
IR blaster |
/media-player |
POST |
action |
Media playback control |
/storage-get |
POST |
output |
Get file via Android SAF |
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
- All commands are checked against a risk assessment system. Dangerous patterns (like
rm -rf / or writes to /dev/) are blocked.
- Paths targeting
/dev/, /proc/, or /sys/ are rejected with canonical path resolution.
- Numeric parameters are validated before shell interpolation to prevent injection.
- When
TERMUX_MCP_AUTH_TOKEN is set, all POST endpoints and the WebSocket endpoint require a Bearer token. WebSocket accepts it via the Authorization header or ?token= query parameter (for clients that can't set headers).
- Non-loopback binding enforces mandatory authentication.
- Request body size is capped at 5 MB.
- Each WebSocket connection keeps its own
cd state (previously a shared global); HTTP keeps per-thread state.
License
MIT
