nano-mcp-termux

nano-mcp-termux

AI エージェント向けの、依存関係ゼロ、単一ファイルの MCP サーバーです。Termux（Android）、Raspberry Pi、Linux でネイティブに動作します。

🚀 クイックスタート

ローカル（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

ヘルスチェック（1回実行、MCP ハンドシェイクなし）

python3 nano_mcp_termux.py --health

🔌 MCP クライアントへの接続

このサーバーは単独では動作しません。MCP プロトコル経由で AI クライアントが接続するサイドカーです。
以下に、最も一般的な 3 つの組み込み方法を示します。

オプション 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	GUI → MCP セクション（通常は ~/.cherrystudio/mcp/*.json が自動作成されます）	上記と同じ JSON スキーマ
Operit	~/.operit/mcp_config.json（またはワークスペースフォルダー内のワークスペース別設定）	∆ mcpServers キーはトップレベルに配置

ヒント： 設定ファイルを編集した後、新しいサーバーが検出されるよう AI クライアントを再起動してください。クライアントがホットリロードに対応している場合は、再起動が不要なこともあります。

トラブルシューティング

症状	考えられる原因	対処方法
クライアントに「server not found」と表示される	command のパスが誤っている、または PATH に含まれていない	絶対パスを使用してください（pip インストールの場合は /usr/local/bin/nano-mcp-termux、pip --user の場合は $HOME/.local/bin/nano-mcp-termux）
Error: spawn uvx ENOENT	uvx が PATH にない（未インストール）	カスタムシェル（"shell": "uw uvx"）または Python の直接起動（Option 2）を使用してください
「Connection lost」／プロセスがすぐに終了する	クライアントから stdin が渡されていない	このサーバーは stdio 経由で動作します。nano-mcp-termux のように直接実行せず、必ずクライアントの MCP 設定経由で起動してください

---

🛠️ 機能

• ✅ 依存関係ゼロ：外部パッケージは不要です
• ✅ 単一ファイル：すべてのロジックを1つのPythonスクリプトに収めています
• ✅ クロスプラットフォーム：Termux（Android）、Raspberry Pi、Linux、およびDocker内で動作します
• ✅ コンテナー対応：Glamaのイントロスペクション用に、リポジトリのルートにDockerfileがあります
• ✅ 標準のstdioフレーミング：改行区切りのJSON-RPC（公式MCPトランスポート）
• ✅ バージョンネゴシエーション：クライアントのprotocolVersion（2024-11-05 / 2025-06-18 / 2025-11-25）をエコーし、対応していない場合はサポート対象の最高バージョンにフォールバックします
• ✅ 段階的な機能縮退：device_statusは失敗せず、利用できない入力にはクラッシュではなく利用不可のマークを付けます
• ✅ [lifecycle] 孤立プロセスなし：各コマンドを専用のプロセスグループで実行します。タイムアウト時はシェルだけでなく、プロセスツリー全体を終了します（SIGTERM → SIGKILL）
• ✅ [lifecycle] 自動終了：親プロセスの監視機能、stdinのEOF検出、任意のアイドルタイムアウトにより、クライアントが停止してもゾンビサーバーが残りません
• ✅ [lifecycle] Phantom Process Killerを考慮：Android 12以降の子プロセス数のリスクを、具体的な緩和策とともに報告します
• ✅ [paths] Android/Termuxパスアダプター：/sdcard ↔ /storage/emulated/0 ↔ $HOME/storage/sharedを解決し、noexecマウント、大文字小文字を区別しないファイルシステム、シェルのクォートに関する危険性を検出します

🧩 ツールの概要

ツール	説明
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ラッパーだけです。シェルがすでに起動していたプロセスは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 のビルダーがこのリポジトリをインストールして内省できるかという 1 つの問いです。Glama が使用するのと同じツールチェーン（uv venv && uv pip install -e .、つまり多くの開発マシンより新しい setuptools）を再現し、コンソールのエントリーポイントが存在することと、サーバーが stdio 経由で initialize と tools/list に応答することを検証します。失敗の原因がどちらにあるのかをスクリプトが決して曖昧にしないよう、終了コードは意図的に 3 種類に分けています。

終了コード	意味
0	ビルドと内省が問題なく完了しました
1	このリポジトリに実際の問題があります（メタデータの誤り、エントリーポイントの欠落、ツールがないなど）
2	ローカル環境の問題です（uv がない、インデックスに接続できない、ミラーが 403 を返すなど）

インデックスは意図的に pypi.org に固定しています。シェルプロファイルから引き継いだローカルミラーが 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 実装として機能するように設計されています。