termux-mcp

KO | EN

gitlite — search

#artificial-intelligence #mcp #automation #nodejs #ios #postgresql #c #css #awesome-list #windows

(★ 9)

Connect Termux to any of your ai apps/agents.

File Explorer

ZIP Download

- - release.yml
- page-2026-08-22T07-16-46-527Z.yml
- - main.go
  - main_test.go
  - update.go
- CONFIGURATION.md
- REMOTE_ACCESS.md
- SECURITY.md
- - audit.go
  - audit_test.go
- - auth.go
  - auth_test.go
- - config.go
  - config_test.go
- - exec.go
  - exec_test.go
- - registry.go
  - registry_test.go
- - server.go
  - sse.go
  - terminal.go
- - tasks.go
  - tasks_test.go
- - register.go
- - tunnel.go
- - version.go
- boot.sh
- install.sh
.gitignore
config.example.yaml
go.mod
go.sum
LICENSE
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A MCP to connect Termux to any AI apps/agents of your choice like Mobile Agent ChatGPT, Claude, or any other

## Demo

[![Termux MCP demo](https://img.youtube.com/vi/nLKPv9LPL1Y/maxresdefault.jpg)](https://youtu.be/nLKPv9LPL1Y?si=myEdb6Akhl9OaUEH)

## Features

- **9 tool modules** — battery, SMS, camera, clipboard, files, UI automation,
  shell (allowlist-only), and more (see the table below)
- **Default-deny security** — sensitive and dangerous tools are opt-in;
  the shell tool is allowlist-only; the server refuses to bind a non-loopback
  address without an auth token
- **Sandboxed filesystem** — file tools resolve symlinks and reject anything
  outside `tools.file_roots`
- **Audit trail** — JSONL log of every tool call with argument redaction
- **Detached background tasks** — long-running jobs survive server restarts
- **Supervised service** — integrates with `termux-services` and Termux:Boot

## Requirements

- An Android device with [Termux](https://f-droid.org/packages/com.termux/)
  installed (from F-Droid)
- The **Termux:API** app from the same source (F-Droid)
- Go ≥ 1.25 only when building from source (the prebuilt install needs no Go)

## One-command install

On the device, inside Termux:

```bash
curl -fsSL https://github.com/TecnicalBot/termux-mcp/raw/main/scripts/install.sh | bash
```

## Manual quick start

```bash
# In Termux:
pkg install -y golang termux-api
go mod tidy
go build -o "$PREFIX/bin/termux-mcp" ./cmd/termux-mcp

termux-mcp doctor        # check environment
termux-mcp               # serve over stdio (default)
```

After installing a released build, update it in place with:

```bash
termux-mcp update
# Or install a specific release:
termux-mcp update --version v0.2.0
```

The updater downloads the Android arm64 release atomically and restarts the
supervised `termux-mcp` service when `termux-services` is available.

## Connecting a client

### stdio (local, on-device agents)

```json
{
  "mcpServers": {
    "termux": {
      "command": "termux-mcp",
      "args": ["serve", "stdio"]
    }
  }
}
```

### LAN (Streamable HTTP)

```bash
termux-mcp token new --write
termux-mcp serve http --config $PREFIX/var/lib/termux-mcp/config.yaml
# => http://192.168.x.x:3000/mcp
```

```json
{
  "mcpServers": {
    "termux": {
      "url": "http://192.168.1.20:3000/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}
```

### Remote (local OR cloudflared quick tunnel)

```bash
termux-mcp serve http &          # loopback is enough
termux-mcp tunnel start          # prints https://xxx.trycloudflare.com
```

See [Remote access](docs/REMOTE_ACCESS.md) for full client configs, including
stdio-only hosts via `mcp-remote`.

## Tool modules

| Module               | Tier          | Tools                                                                                                         |
| -------------------- | ------------- | ------------------------------------------------------------------------------------------------------------- |
| A. Device & System   | safe          | battery, device info, storage, screen size, brightness, volume, vibrate, flashlight, wifi, telephony, sensors |
| B. Communication     | sensitive\*   | sms list/send, contacts, call log, calls, notifications, toasts                                               |
| C. Media             | sensitive\*   | camera photo/info, audio record, media player, tts/stt                                                        |
| D. Clipboard & Input | safe          | clipboard get/set, open url, open app                                                                         |
| E. Files             | sensitive\*   | list/read/write/download/share/media-scan (sandboxed)                                                         |
| F. UI Automation     | dangerous\*\* | screenshot, ui dump, tap, swipe, text, keyevents                                                              |
| G. Shell & Tasks     | safe          | execute_command (launch detached task, optional workdir), task_status, task_log                                          |
| H. Utility           | safe          | ping, server_status, get_config, list_tools                                                                   |
| I. Task control      | dangerous\*\* | stop_task, task_delete (terminate/delete running tasks)                                                        |

\* opt-in via `tools.enable_sensitive: true` \
\*\* opt-in via `tools.enable_dangerous: true` (and allowlists)

## Configuration

Copy `config.example.yaml` to `$PREFIX/var/lib/termux-mcp/config.yaml` and
`chmod 600`. Every key can be overridden with a `TERMUX_MCP_*` environment
variable. Full reference: [Configuration](docs/CONFIGURATION.md).

```yaml
server:
  mode: stdio # stdio | http
  bind: 127.0.0.1 # non-loopback binds REQUIRE auth.token
  port: 3000

auth:
  token: "" # generate: termux-mcp token new --write
  require: false

tools:
  enable_sensitive: false # modules B, C, E
  enable_dangerous: false # modules F, I

exec:
  default_timeout_seconds: 30
  shell_allowed: false # allowlist-only when enabled
  shell_allow_patterns: [] # e.g. ["^ls ", "^df "]
```

## Security

- Default-deny tool tiers; nothing sensitive is exposed unless you opt in
- Non-loopback binds and tunnels refuse to start without an auth token
- Bearer tokens compared in constant time; config files written `0600`
- File access is sandboxed to `tools.file_roots` with symlink resolution
- Every tool call lands in a JSONL audit log with secrets redacted

Read the full model: [Security](docs/SECURITY.md).

## Development

```bash
go build ./...
go vet ./...
go test ./...        # unit tests use sh-based command fixtures; no device required
```

## Repository layout

```
cmd/termux-mcp        CLI entrypoint
internal/config       YAML config + env overrides + validation + discovery
internal/registry     tool catalog, tiers, tools/list filtering
internal/exec         safe exec wrapper (timeout, caps, retry-once)
internal/audit        JSONL audit log with arg redaction
internal/auth         constant-time bearer token middleware
internal/server       stdio + Streamable HTTP wiring
internal/tools/*      the 9 tool modules
internal/tunnel       cloudflared quick tunnel
scripts/              install.sh (one-command installer), boot.sh (boot entry)
docs/                 configuration, remote access, security
```

## Docs

- [Configuration](docs/CONFIGURATION.md)
- [Remote access (tunnels + auth)](docs/REMOTE_ACCESS.md)
- [Security model](docs/SECURITY.md)

## License

MIT

termux-mcp

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

termux-mcp

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README