nano-mcp-termux

nano-mcp-termux

零依赖、单文件 MCP 服务，可在 Termux（Android）、Raspberry Pi 和 Linux 上原生运行，供 AI Agent 使用。

🚀 快速开始

本地运行（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

健康检查（一次性运行，无需 MCP 握手）

python3 nano_mcp_termux.py --health

🔌 连接到 MCP 客户端

此服务不会独立运行——它是一个sidecar，由 AI 客户端通过 MCP 协议连接。
以下是最常见的三种接入方式。

选项 1 — 零安装（uvx），适用于桌面 AI 客户端

uvx nano-mcp-termux

然后将此 JSON 添加到 AI 客户端的 mcpServers 配置中（参见下方针对特定客户端的说明）：

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

选项 2 — 已通过 pip install 安装，或更倾向于直接启动 Python

pip install nano-mcp-termux

AI 客户端的配置片段：

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

选项 3 — 直接运行单个文件（例如在 Android 上的 Termux 中）

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

AI 客户端的配置片段：

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

---

如何使用这些配置片段：针对特定客户端的配置文件

AI 客户端	配置文件位置（示例）	备注
Claude Desktop	macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json	∆ 顶层的 mcpServers 键
Cursor	~/.cursor/mcp.json	∆ 顶层的 mcpServers 键
Cline	$HOME/.cliner/mcp.json（或项目文件夹中的 cline_mcp_settings.json）	∆ 顶层的 mcpServers 键
Cherry Studio	图形界面 → MCP 部分（通常会自动创建 ~/.cherrystudio/mcp/*.json）	JSON 架构同上
Operit	~/.operit/mcp_config.json（或工作区文件夹中的工作区配置）	∆ 顶层的 mcpServers 键

*提示：*编辑配置文件后，请重启 AI 客户端，以便检测到新服务。如果客户端支持热重载，则可能无需重启。

故障排除

问题	可能原因	解决方法
客户端显示“找不到服务”	command 路径错误或不在 PATH 中	使用绝对路径（通过 pip 安装时为 /usr/local/bin/nano-mcp-termux，通过 pip --user 安装时为 $HOME/.local/bin/nano-mcp-termux）
Error: spawn uvx ENOENT	uvx 不在 PATH 中（未安装）	使用自定义 shell，例如 "shell": "uw uvx"，或直接启动 Python（选项 2）
“连接丢失”／进程立即退出	客户端未提供 stdin	此服务依赖 stdio；不要直接运行 nano-mcp-termux，务必通过客户端的 MCP 配置启动

---

🛠️ 功能

• ✅ 零依赖：无需外部软件包
• ✅ 单文件：所有逻辑都在一个 Python 脚本中
• ✅ 跨平台：可在 Termux（Android）和 Raspberry Pi、Linux 上运行，也可在 Docker 容器内运行
• ✅ 支持容器：仓库根目录中的 Dockerfile 供 Glama 进行检查
• ✅ 标准 stdio 帧格式：以换行符分隔的 JSON-RPC（官方 MCP 传输方式）
• ✅ 版本协商：回显客户端的 protocolVersion（2024-11-05 / 2025-06-18 / 2025-11-25），否则回退到支持的最高版本
• ✅ 优雅降级：device_status 永不失败；不可用的输入会标记为不可用，而不会导致崩溃
• ✅ [lifecycle] 不遗留孤儿进程：每条命令都在独立的进程组中运行；超时后会终止整个进程树（SIGTERM → SIGKILL），而不只是 shell
• ✅ [lifecycle] 自动终止：通过父进程看门狗、stdin EOF 检测和可选的空闲超时，确保客户端退出后不会留下僵尸服务
• ✅ [lifecycle] 兼顾 Phantom Process Killer：报告 Android 12+ 子进程数量风险，并提供具体的缓解措施
• ✅ [paths] Android/Termux 路径适配器：解析 /sdcard ↔ /storage/emulated/0 ↔ $HOME/storage/shared，检测 noexec 挂载、大小写不敏感的文件系统，以及 shell 引号风险

🧩 工具概览

工具	描述
device_status	汇总设备信息：电池 / 存储 / 架构 / 内存（已降级的字段会标记为不可用）
server_health	运行时健康状况：pid/ppid/env、运行时间、请求计数器、活动子进程、回收策略、RSS、Phantom Process Killer 风险
resolve_path	解析 Android/Termux 路径：规范形式、挂载点、noexec/只读标志、大小写敏感性、等效拼写形式、引号警告
path_adapter	环境配置：运行时类别、$HOME/$PREFIX/$TMPDIR、带挂载摘要的 Android 存储根目录、noexec 挂载列表

🔗 协议接口

方法	行为
initialize	回显客户端支持的版本（2024-11-05 / 2025-06-18 / 2025-11-25），否则根据 MCP 规范返回支持的最高版本；声明 {"tools": {}}
notifications/initialized	静默（不作响应）
ping	返回 {}
tools/list	返回工具目录
tools/call	返回 {"content": [{"type": "text", ...}]}
未知方法 / 工具	返回 -32601 / -32602 JSON-RPC 错误
JSON 格式错误	返回 -32700 解析错误

🔄 为什么是 1.1.0：孤儿进程漏洞

1.0.0 版本使用 subprocess.run(..., timeout=...) 运行命令。超时后， Python 只会终止直接子进程，也就是 sh -c 包装进程。shell 已经派生的任何进程都会被重新托管给 init，并且永远不会终止。在 Android 上，这种泄漏正是会触发 Phantom Process Killer 的类型，并可能导致整个应用组被终止。

1.1.0 从根本上修复了这个问题：通过 start_new_session=True 启动命令，并使用 os.killpg(pgid, SIGTERM) → SIGKILL 拆除进程，因此整个进程 树会一起终止。

仓库提供了可复现的 A/B 回归测试：

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

✅ 测试

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 回答一个问题：Glama 的构建器能否安装此仓库并检查其内容？ 它会重放 Glama 使用的相同工具链（uv venv && uv pip install -e .，也就是说，使用比大多数开发机器更新的 setuptools），然后断言控制台入口点存在，并且服务可通过标准输入/输出响应 initialize 和 tools/list。退出代码刻意分为三种，确保脚本不会错误归咎：

退出码	含义
0	构建和检查均顺利完成
1	此仓库存在实际问题（元数据错误、缺少入口点、没有工具）
2	本地环境问题（没有 uv、无法访问索引、镜像返回 403）

索引特意固定为 pypi.org——从 shell 配置文件继承的本地镜像可能返回 403，让正常的仓库看起来像是有问题。只有在确有需要时，才使用 GLAMA_VERIFY_INDEX=https://your-mirror/simple 覆盖。

关于 project.license 的弃用警告是预期的，不会导致失败：要消除这些警告，需要使用 SPDX 格式，而这要求 setuptools>=77，也就要求 Python 3.9+；但此项目仍支持通过源码在 Python 3.8 上构建。

⚙️ 环境变量

变量	默认值	用途
NANO_IDLE_TIMEOUT	0（关闭）	服务在无活动状态下自行退出前等待的秒数
NANO_NO_WATCHDOG	未设置	设置为 1 可禁用父进程看门狗线程

🔗 链接

• 原始仓库：Lmeng486/nano-mcp-termux
• 验证报告：awesome-termux-mcp
• 实测开销报告（以此服务为测试对象，所有数据均来自真实设备）：MCP on Mobile: Measured Overhead Report
• Dev.to 文章：Showdev：一款可在 Android Termux 上运行的零依赖 MCP 服务
• Glama 评分验证（TDQS 4.6 / A 级，含版本元数据取证）：docs/GLAMA-SCORE.md

---

此服务旨在通过 Glama 检查，并作为面向移动设备和边缘设备的轻量级 MCP 实现。