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

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

System Monitor & Management

Cron Scheduler

Backup, Restore & Cloud Sync

Code & Files

Device & Sensors

Communication

Network

Media

Smart Tools

Git Operations

SSH, Services & Migration

Other

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

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.