Termux API & PRoot-Distro Ubuntu と MCP Server

このプロジェクトは、Termux経由でAndroid上に proot-distro を使用してUbuntuをインストールし、AndroidシステムAPIをその中にバインドし、Pythonベースの Model Context Protocol (MCP) サーバーを起動するブートストラップスクリプトを提供します。

このMCPサーバーをスマートフォンで実行すると、外部のAIクライアント（Cursor、Claude Desktop、Windsurf、独自のHTTPエージェントなど）に、Android端末のハードウェア制御、センサー読み取り、通信情報の取得、シェルコマンドの実行といった完全な機能を与えられます。

クイックスタート（3ステップのセットアップ）

ステップ1: TermuxにUbuntuをインストールして設定する

ネイティブのTermuxターミナルで次のコマンドを実行して、Ubuntuをインストール、設定し、ログインします。 （これは最初にスクリプトをダウンロードするため、stdinがキーボードに接続されたままになり、正しくログインできます。）

curl -sLO https://raw.githubusercontent.com/AbuZar-Ansarii/Termux-MCP/main/install_ubuntu.sh && chmod +x install_ubuntu.sh && ./install_ubuntu.sh

このスクリプトが完了すると、自動的にUbuntuへログインし、次のプロンプトが表示されます: root@localhost:~#

ステップ2: リポジトリをクローンしてMCPをセットアップする（Ubuntu内）

Ubuntuコンテナ内（root@localhost:~#）に入ったら、次のコマンドをコピー＆ペーストして、リポジトリをクローンし、セットアップスクリプトを実行し、仮想環境を有効化してください:

git clone https://github.com/AbuZar-Ansarii/Termux-MCP.git && cd Termux-MCP && chmod +x setup_mcp.sh && ./setup_mcp.sh && source venv/bin/activate

（source venv/bin/activate 文を末尾に追加することで、そのコマンドが親シェルコンテキストで実行されるようになります。完了すると、有効化された仮想環境内で次のプロンプトが表示されます: (venv)root@localhost:~/Termux-MCP#。）

ステップ3: MCPサーバーを実行する

有効な仮想環境内で、サーバーを直接実行してください:

python termux_mcp.py --transport sse

サーバーが起動すると、スマートフォンのIPアドレスを検出し、コピー＆ペースト可能な接続URL（例: http://192.168.1.15:8000/sse）を表示します。これをそのままAIクライアントに接続できます。

今後のショートカットコマンド

今後は（手動でログインや有効化をせずにネイティブTermuxから）1つのコマンドでサーバーを起動できます:

proot-distro login ubuntu -- bash /root/run_mcp.sh

Related MCP server: android-shizuku-mcp

PRoot-Distro Ubuntuを使う理由

proot-distro を使ってTermux内でUbuntuのようなLinuxディストリビューションを実行することには、いくつかの大きな利点があります:

1. Glibc（GNU Cライブラリ）互換性: AndroidとネイティブTermuxはBionic libcを使用しており、パスや標準が異なります。多くのコンパイル済みパッケージ、データベースバイナリ、Nodeモジュール、Pythonライブラリは、コンパイルエラーなく実行するために標準の glibc を必要とします。PRoot-Distro Ubuntuは標準の glibc 環境を提供します。

2. パッケージの豊富さとエコシステム: Ubuntuを使うと、膨大な apt パッケージアーカイブにアクセスできます。ワークフローが標準的なLinuxサーバーツール、デスクトップパッケージ、またはコンパイル済みサービスを必要とする場合、それらをUbuntu rootfsで実行する方が、ネイティブのAndroid/Bionic用にパッチを当てるよりはるかに堅牢です。

3. 分離とサンドボックス: PRoot Ubuntu内で開発することで、ホストのTermuxファイルシステムをクリーンでモジュール式に保てます。何かが壊れた場合や新しくやり直したい場合は、Termuxの設定を失うことなく配布コンテナをリセットするだけです。

4. ハードウェアAPIブリッジ: ブートストラップスクリプトは、Termuxネイティブの $PREFIX フォルダーをUbuntuにバインドします。つまり、両方の長所を兼ね備えているということです。カメラ、トースト、位置情報、センサーなどのAndroid APIへの直接のコマンドラインアクセスを備えた、フル機能のUbuntu Linux環境が得られます。

機能（MCPツール）

MCPサーバーは、スマートフォンを制御するための完全なツールセットを公開します:

• システムとハードウェア:

  • get_battery_status: デバイスのバッテリー残量、健全性、温度、充電状態を読み取ります。

  • toggle_torch: フラッシュライト/トーチをON/OFFにします。

  • set_screen_brightness: 画面の明るさを変更します（0〜255）。

  • get_volume_info & set_volume: アラーム、音楽、着信音、通話、システム、通知の各ボリュームストリームのレベルを読み取りまたは設定します。

• 通信:

  • list_contacts: スマートフォンに保存されているすべての連絡先の名前と電話番号を一覧表示します。

  • get_call_log: 最近の通話履歴を取得します。

  • list_sms & send_sms: 受信トレイ/送信済みメッセージを一覧表示し、新しいテキストメッセージを送信します。

• センサーとネットワーク:

  • get_location: 正確なGPSまたはネットワークベースの座標を取得します。

  • get_wifi_connection_info: Wi-Fi接続のメタデータ（SSID、BSSID、IP、リンク速度）を取得します。

  • get_telephony_device_info: 通信キャリア、電波強度、ネットワークタイプを照会します。

• メディアと写真:

  • take_photo: フロントカメラまたはリアカメラで写真を撮影し、デバイス上のファイルパスに保存します。

  • tts_speak: Google TTSを使用して音声を合成します。

• ユーザー操作とクリップボード:

  • show_toast: スマートフォンの画面に一時的なトースト通知を表示します。

  • vibrate_phone: 設定した時間だけデバイスを振動させます。

  • clipboard_get & clipboard_set: Androidのクリップボードを読み書きします。

  • show_notification: 標準のAndroid通知を表示します。

  • prompt_user_dialog: スマートフォンに対話式のテキスト入力ダイアログを表示し、AIクライアントへの応答を入力できるようにします。

  • share_text: テキストをAndroidのネイティブ共有シートに直接共有します。

• 任意の実行:

  • execute_command: ネイティブのTermuxホストで任意のシェルコマンドを直接実行します。

詳しいステップバイステップのインストール

ステップ1: AndroidにTermuxとTermux:APIをインストールする

1. Termux アプリと Termux:API アプリをインストールします。

   • 必須: 両方のアプリを F-Droid からインストールしてください（F-Droid版とPlay Store版を混在させないでください。これらのバージョンは互いに署名/バインドされず、連携できないためです）。

2. Androidの設定 -> アプリ -> Termux:API -> 権限 の順に開きます。

   • カメラ、位置情報、SMS、連絡先、ストレージ の権限を許可します。

3. Termux と Termux:API の両方で バッテリー最適化を無効化 して、Androidがバックグラウンドサービスを終了しないようにします。

ステップ2: セットアップスクリプトを実行する

Termuxを開き、次のコマンドを貼り付けます:

curl -sLO https://raw.githubusercontent.com/AbuZar-Ansarii/Termux-MCP/main/install_ubuntu.sh && chmod +x install_ubuntu.sh && ./install_ubuntu.sh

ステップ3: MCPサーバーのセットアップを実行する

Ubuntuコンテナ内に入ったら:

git clone https://github.com/AbuZar-Ansarii/Termux-MCP.git && cd Termux-MCP && chmod +x setup_mcp.sh && ./setup_mcp.sh && source venv/bin/activate

ステップ4: サーバーを起動する

有効化された環境（(venv)root@localhost:~/Termux-MCP#）で:

python termux_mcp.py --transport sse

ターミナルに接続URLが表示されます:

==================================================================
   🤖 Termux MCP Server Running in SSE Mode
==================================================================
   👉 SSE Connect URL: http://192.168.1.15:8000/sse
   👉 Messages URL:    http://192.168.1.15:8000/messages/
==================================================================

ステップ5: AIクライアントに接続する

Server-Sent Events (SSE) 経由のMCPをサポートする任意のクライアントを接続できます。

Cursorを接続する

1. Cursorの設定 -> 機能 -> MCP を開きます。

2. + 新しいMCPサーバーを追加 をクリックします。

3. 次のように入力します:

   • 名前: termux-mcp

   • 種類: SSE

   • URL: http://YOUR_PHONE_IP:8000/sse （サーバーが表示する「SSE Connect URL」をコピー＆ペーストしてください）

4. 保存 をクリックします。

Claude Desktopとの接続（SSH経由の代替Stdio）

SSH経由でローカルのstdioコマンドを実行したい場合は、リポジトリドキュメントのOption B を参照して、OpenSSHキーを設定し、ローカルの %APPDATA%\Claude\claude_desktop_config.json を構成してください。

トラブルシューティング

• ツール呼び出しがハングする場合: get_location や take_photo などのツール呼び出しがハングしたら、Android設定で Termux:API アプリに権限が付与されていることと、バッテリーセーバーがオフであることを確認してください。

• 接続拒否: PCとスマートフォンが同じWi-Fiネットワークに接続されていることと、サーバーが実行中であることを確認してください。

• Termuxのバックグラウンド実行: Androidは画面がロックされている間、Termuxプロセスを一時停止することがあります。Androidの通知ドロワーを下ろし、Termuxが「1 session」と表示し、「Acquire wake lock」が有効になっていることを確認して、バックグラウンドで実行し続けるようにしてください。