io.github.Lmeng486/nano-mcp-termux

nano-mcp-termux

Zero-dependency, single-file MCP server for AI agents, natively running on Termux (Android), Raspberry Pi, and Linux.

🚀 Quick Start

Local (Termux / Linux)

cd /path/to/nano-mcp-termux
python3 nano_mcp_termux.py

Docker

docker build -t nano-mcp-termux .
docker run -i --rm nano-mcp-termux

Health check (one-shot, no MCP handshake)

python3 nano_mcp_termux.py --health

🔌 Connect to your MCP client

This server does not run standalone — it's a sidecar that your AI client connects to via the MCP protocol.
Below are the three most common ways to mount it.

Option 1 — Zero‑install (uvx), best for desktop AI clients

uvx nano-mcp-termux

Then add this JSON to your AI client's mcpServers config (see client‑specific notes below):

{
  "mcpServers": {
    "nano-mcp-termux": {
      "command": "uvx",
      "args": ["nano-mcp-termux"]
    }
  }
}

Option 2 — Already pip installed, or you prefer a direct Python launch

pip install nano-mcp-termux

Config snippet for your AI client:

{
  "mcpServers": {
    "nano-mcp-termux": {
      "command": "nano-mcp-termux"
    }
  }
}

Option 3 — Run the single file directly (e.g. inside Termux on Android)

# Clone or download the repo, then:
cd /path/to/nano-mcp-termux
python3 nano_mcp_termux.py

Config snippet for your AI client:

{
  "mcpServers": {
    "nano-mcp-termux": {
      "command": "python3",
      "args": ["/full/path/to/nano_mcp_termux.py"]
    }
  }
}

How to use these snippets: client‑specific config files

Tip: after editing the config file, restart your AI client so the new server is detected. If the client supports hot‑reload, you may not need a restart.

Troubleshooting

🛠️ Features

• ✅ Zero-dependency: No external packages required
• ✅ Single-file: All logic in one Python script
• ✅ Cross-platform: Works in Termux (Android), on Raspberry Pi, Linux, and inside Docker
• ✅ Container-ready: Dockerfile at repo root for Glama introspection
• ✅ Standard stdio framing: Newline-delimited JSON-RPC (official MCP transport)
• ✅ Version negotiation: Echoes client protocolVersion (2024-11-05 / 2025-06-18 / 2025-11-25), falls back to highest supported
• ✅ Graceful degradation: device_status never fails; unavailable inputs are marked, not crashed
• ✅ [lifecycle] No orphaned processes: every command runs in its own process group; timeouts kill the whole tree (SIGTERM → SIGKILL), never just the shell
• ✅ [lifecycle] Self-terminating: parent-process watchdog + stdin-EOF detection + optional idle timeout, so a dead client never leaves a zombie server behind
• ✅ [lifecycle] Phantom Process Killer aware: reports Android 12+ child-count risk with concrete mitigations
• ✅ [paths] Android/Termux path adapter: resolves /sdcard ↔ /storage/emulated/0 ↔ $HOME/storage/shared, detects noexec mounts, case-insensitive filesystems, and shell-quoting hazards

🧩 Tools Overview

🔗 Protocol Surface

🔄 Why 1.1.0: the orphan-process bug

Version 1.0.0 ran commands with subprocess.run(..., timeout=...). On timeout, Python terminates only the direct child — the sh -c wrapper. Anything the shell had already spawned is reparented to init and survives forever. On Android that is the exact leak class that trips the Phantom Process Killer and can get the whole app group killed.

1.1.0 fixes this at the root: commands are spawned with start_new_session=True and torn down with os.killpg(pgid, SIGTERM) → SIGKILL, so the entire process tree dies together.

The repository ships a reproducible A/B regression test for it:

python3 test_lifecycle_orphan.py
# current  nano_mcp_termux.py           leaked_grandchildren=0
# legacy   nano_mcp_termux_v10_backup.py leaked_grandchildren=1   <- the bug
# PASS: current server leaves 0 orphaned grandchildren after timeout

✅ Tests

python3 test_client.py            # 32 protocol / tool / lifecycle assertions
python3 test_lifecycle_orphan.py  # orphan-leak A/B regression (1.0.0 vs 1.1.0)
bash scripts/verify_glama_build.sh # Glama-build reproduction (see below)

verify_glama_build.sh answers one question: will Glama's builder be able to install and introspect this repo? It replays the same toolchain Glama uses (uv venv && uv pip install -e ., i.e. a newer setuptools than most dev machines have), then asserts the console entry point exists and that the server answers initialize + tools/list over stdio. Exit codes are deliberately three-valued so the script never lies about whose fault a failure is:

The index is pinned to pypi.org on purpose — a local mirror inherited from your shell profile can return 403 and make a healthy repo look broken. Override with GLAMA_VERIFY_INDEX=https://your-mirror/simple only if you mean it.

Deprecation warnings about project.license are expected and non-fatal: the SPDX form that silences them needs setuptools>=77, which requires Python 3.9+, while this project still supports 3.8 source builds.

⚙️ Environment variables

🔗 Links

• Original repository: Lmeng486/nano-mcp-termux
• Verification report: awesome-termux-mcp
• Measured overhead report (this server as subject under test, all numbers from a real device): MCP on Mobile: Measured Overhead Report
• Dev.to article: Showdev: A zero-dependency MCP server that runs on Android Termux
• Glama score verification (TDQS 4.1 / grade A, with version-metadata forensics): docs/GLAMA-SCORE.md

This server is designed to pass Glama introspection checks and serve as a lightweight MCP implementation for mobile and edge devices.