Nano Mcp Termux

io.github.Lmeng486Published by GitHub account Lmeng486v1.1.1Updated Oct 24, 2026

Zero-dependency single-file MCP server for Termux/Android, Raspberry Pi and Linux

VerifiedSTDIODesktop onlyCloud & InfrastructureDeveloper Tools

Overview

AI-generated overview

A zero-dependency, single-file Python MCP server for Termux/Android, Raspberry Pi and Linux that reports device, runtime and path information to an AI…

What you can do
  • Inspect the device: battery, storage, architecture and memory via device_status
  • Check server runtime health: process IDs, uptime, request counters, live children, memory use and Android process-killer risk
  • Resolve Android/Termux paths: canonical form, mount point, noexec or read-only flags, case sensitivity and quoting warnings
  • Read the environment profile: runtime class, home, prefix and temp directories, Android storage roots and noexec mounts
When to use it
Useful when running an AI client on Android/Termux, a Raspberry Pi or a small Linux box and you want the assistant to see device state, server health and filesystem quirks before running commands. It is a diagnostic sidecar, not a general command runner.
Requirements
Runs locally as a stdio process launched by the MCP client. Needs Python 3 (3.8+ source builds) or uvx/pip for the PyPI package; Docker is optional. No accounts, API keys or network access are declared. Optional environment variables NANO_IDLE_TIMEOUT and NANO_NO_WATCHDOG tune idle exit and the watchdog.
Before you install
It must be launched through the client's MCP config, not run directly, since it is stdio-bound. It exposes device and environment details such as paths, process IDs and environment values to the assistant, so review what your client logs or shares. It is read-only diagnostics; no write or delete tools are listed.

Installation

In SourceWeft

  1. Open Nano Mcp Termux in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

nano-mcp-termux

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

[GitHub Repository] [License: MIT] [MCP Version] [Docker Ready] [Version] [Tests] [CI] [Zero Dependencies]

🚀 Quick Start

Local (Termux / Linux)

bash
cd /path/to/nano-mcp-termuxpython3 nano_mcp_termux.py

Docker

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

Health check (one-shot, no MCP handshake)

bash
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

bash
uvx nano-mcp-termux

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

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

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

bash
pip install nano-mcp-termux

Config snippet for your AI client:

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

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

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

Config snippet for your AI client:

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

How to use these snippets: client‑specific config files

AI clientConfig file location (examples)Note
Claude DesktopmacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json		∆ mcpServers key at top level
Cursor~/.cursor/mcp.json∆ mcpServers key at top level
Cline$HOME/.cliner/mcp.json (or inside project folder as cline_mcp_settings.json)∆ mcpServers key at top level
Cherry StudioGUI → MCP section (typically auto‑creates ~/.cherrystudio/mcp/*.json)JSON schema as above
Operit~/.operit/mcp_config.json (or per‑workspace config in the workspace folder)∆ mcpServers key at top level

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

SymptomLikely causeFix
Client shows "server not found"command path is wrong or not in PATHUse absolute path (/usr/local/bin/nano-mcp-termux for pip installs, $HOME/.local/bin/nano-mcp-termux for pip --user)
Error: spawn uvx ENOENTuvx not in PATH (not installed)Use a custom shell like "shell": "uw uvx" or the direct Python launch (Option 2)
"Connection lost" / process dies immediatelyNo stdin from clientThis server is stdio‑bound; don't run it directly like nano-mcp-termux — always launch it through your client's MCP config

🛠️ 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

ToolDescription
device_statusAggregate device info: battery / storage / arch / memory (degraded fields marked unavailable)
server_healthRuntime health: pid/ppid/env, uptime, request counters, live children, reaping policy, RSS, Phantom Process Killer risk
resolve_pathResolve an Android/Termux path: canonical form, mount point, noexec/read-only flags, case sensitivity, equivalent spellings, quoting warnings
path_adapterEnvironment profile: runtime class, $HOME/$PREFIX/$TMPDIR, Android storage roots with mount summaries, noexec mount list

🔗 Protocol Surface

MethodBehavior
initializeEchoes supported client version (2024-11-05 / 2025-06-18 / 2025-11-25), else responds with highest supported per MCP spec; declares {"tools": {}}
notifications/initializedSilent (no response)
pingReturns {}
tools/listReturns tool catalog
tools/callReturns {"content": [{"type": "text", ...}]}
Unknown method / tool-32601 / -32602 JSON-RPC errors
Malformed JSON-32700 parse error

🔄 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:

bash
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

bash
python3 test_client.py            # 32 protocol / tool / lifecycle assertionspython3 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:

ExitMeaning
0Builds and introspects cleanly
1Real problem in this repo (bad metadata, missing entry point, no tools)
2Local environment problem (no uv, index unreachable, mirror returns 403)

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

VariableDefaultPurpose
NANO_IDLE_TIMEOUT0 (off)Seconds of inactivity before the server exits on its own
NANO_NO_WATCHDOGunsetSet to 1 to disable the parent-process watchdog thread

🔗 Links

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

Source: README.md at commit b37343f

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

2
  1. v1.1.1LatestOct 16, 2026
  2. v1.1.0Oct 12, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts