Termux API & PRoot-Distro Ubuntu with MCP Server

This project provides a bootstrap script to install Ubuntu under proot-distro on Android via Termux, bind Android system APIs into it, and launch a Python-based Model Context Protocol (MCP) server.

With this MCP server running on your phone, you can grant any external AI client (like Cursor, Claude Desktop, Windsurf, or custom HTTP agents) full capability to control your Android device's hardware, read sensors, fetch communications, and execute shell commands.

Quick Start (Three-Step Setup)

Step 1: Install and Configure Ubuntu on Termux

Run this command inside your native Termux terminal to install, configure, and log in to Ubuntu. (This downloads the script first so that stdin stays attached to your keyboard, allowing it to correctly log you in.)

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

Once this script completes, it will automatically log you into Ubuntu, leaving you at the prompt: root@localhost:~#

Step 2: Clone and Setup MCP (Inside Ubuntu)

Once inside the Ubuntu container (root@localhost:~#), copy and paste this command to clone the repository, run the setup script, and activate the virtual environment:

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

(Appending the source venv/bin/activate statement ensures that it runs in your parent shell context. Once completed, you will find yourself inside the activated virtual environment at the prompt: (venv)root@localhost:~/Termux-MCP#.)

Step 3: Run the MCP Server

While inside the active virtual environment, run the server directly:

python termux_mcp.py --transport sse

Once running, the server will detect your phone's IP address and display a copy-pasteable connection URL (e.g., http://192.168.1.15:8000/sse) to plug directly into your AI client!

Future Shortcut Command

For future runs (from native Termux, without manually logging in and activating), you can start the server in one command:

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

Related MCP server: android-shizuku-mcp

Why PRoot-Distro Ubuntu?

Running a Linux distribution like Ubuntu inside Termux using proot-distro offers several key benefits:

1. Glibc (GNU C Library) Compatibility: Android and native Termux use Bionic libc, which differs in paths and standards. Many compiled packages, database binaries, Node modules, and Python libraries require standard glibc to run without compilation failures. PRoot-Distro Ubuntu provides a standard glibc environment.

2. Package Abundance & Ecosystem: Ubuntu gives you access to the massive apt package archives. If your workflow requires standard Linux server tooling, desktop packages, or compiled services, running them in Ubuntu rootfs is far more robust than patching them for native Android/Bionic.

3. Isolation & Sandbox: Developing inside PRoot Ubuntu keeps your host Termux filesystem clean and modular. If something breaks or you want a fresh start, you can simply reset the distribution container without losing your Termux configurations.

4. Hardware API Bridging: Our bootstrap script binds the Termux native $PREFIX folder into Ubuntu. This means you get the best of both worlds: a full-featured Ubuntu Linux environment that still has direct command-line access to Android APIs (like camera, toast, location, and sensors).

Features (MCP Tools)

The MCP server exposes a complete set of tools to control your phone:

• System & Hardware:

  • get_battery_status: Read device battery level, health, temperature, and charging status.

  • toggle_torch: Turn the flashlight/torch ON or OFF.

  • set_screen_brightness: Change the screen brightness (0-255).

  • get_volume_info & set_volume: Read or set levels for alarm, music, ring, call, system, and notification volume streams.

• Communication:

  • list_contacts: List all contact names and phone numbers stored on the phone.

  • get_call_log: Retrieve recent call history.

  • list_sms & send_sms: List inbox/sent messages and send new text messages.

• Sensors & Network:

  • get_location: Retrieve precise GPS or network-based coordinates.

  • get_wifi_connection_info: Get Wi-Fi connection metadata (SSID, BSSID, IP, link speed).

  • get_telephony_device_info: Query telephony carrier, signal strength, and network type.

• Media & Photos:

  • take_photo: Snap front or rear camera photos and save them to a file path on the device.

  • tts_speak: Synthesize spoken speech using Google TTS.

• User Interaction & Clipboard:

  • show_toast: Display temporary toast notifications on the phone screen.

  • vibrate_phone: Vibrate the device for a set duration.

  • clipboard_get & clipboard_set: Read and write the Android clipboard.

  • show_notification: Display standard Android notifications.

  • prompt_user_dialog: Display an interactive text input dialog on the phone, letting you type a response back to the AI client.

  • share_text: Share text directly into Android's native share sheet.

• Arbitrary Execution:

  • execute_command: Run any arbitrary shell command directly in the native Termux host.

Detailed Step-by-Step Installation

Step 1: Install Termux & Termux:API on Android

1. Install the Termux app and the Termux:API app.

   • Required: Install both apps from F-Droid (do not mix F-Droid and Play Store versions, as they will not sign/bind together).

2. Go to Android Settings -> Apps -> Termux:API -> Permissions:

   • Grant Camera, Location, SMS, Contacts, and Storage permissions.

3. Disable Battery Optimization for both Termux and Termux:API to prevent Android from closing the background services.

Step 2: Run the Setup Script

Open Termux and paste the following command:

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

Step 3: Run the MCP Server Setup

Once inside the Ubuntu container:

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

Step 4: Launch the Server

In the activated environment ((venv)root@localhost:~/Termux-MCP#):

python termux_mcp.py --transport sse

The terminal will print the connection 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/
==================================================================

Step 5: Connect to Your AI Client

You can connect any client that supports MCP over Server-Sent Events (SSE).

Connecting Cursor:

1. Open Cursor Settings -> Features -> MCP.

2. Click + Add New MCP Server.

3. Enter:

   • Name: termux-mcp

   • Type: SSE

   • URL: http://YOUR_PHONE_IP:8000/sse (Copy-paste the 'SSE Connect URL' printed by the server)

4. Click Save.

Connecting Claude Desktop (Alternative Stdio over SSH)

If you prefer running local stdio commands piped over SSH, see Option B in the repository documentation to set up OpenSSH keys and configure your local %APPDATA%\Claude\claude_desktop_config.json.

Troubleshooting

• Tool call hangs: If a tool call (like get_location or take_photo) hangs, verify the Termux:API app has permissions granted in Android settings and battery saver is off.

• Connection Refused: Ensure your PC and phone are connected to the same Wi-Fi network and that the server is running.

• Termux Background Execution: Android may suspend Termux processes when the screen is locked. Pull down the Android notification drawer and make sure Termux shows "1 session" with "Acquire wake lock" enabled, keeping it running in the background.