Termux API 与 PRoot-Distro Ubuntu 搭配 MCP 服务器

本项目提供一个引导脚本，用于在 Android 上的 Termux 中通过 proot-distro 安装 Ubuntu，将 Android 系统 API 绑定到其中，并启动一个基于 Python 的 Model Context Protocol (MCP) 服务器。

借助运行在手机上的这个 MCP 服务器，你可以让任何外部 AI 客户端（如 Cursor、Claude Desktop、Windsurf 或自定义 HTTP 代理）完全控制你的 Android 设备硬件、读取传感器、获取通信信息并执行 shell 命令。

快速开始（三步设置）

第 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 语句可确保它在你的父 shell 上下文中运行。完成后，你将处于已激活的虚拟环境中，提示符为：(venv)root@localhost:~/Termux-MCP#。）

第 3 步：运行 MCP 服务器

在已激活的虚拟环境中，直接运行服务器：

python termux_mcp.py --transport sse

运行后，服务器将检测你手机的 IP 地址，并显示一个可复制粘贴的连接 URL（例如 http://192.168.1.15:8000/sse），可直接填入你的 AI 客户端！

未来的快捷命令

对于以后的运行（从原生 Termux，无需手动登录和激活），你可以通过一条命令启动服务器：

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

Related MCP server: android-shizuku-mcp

为什么选择 PRoot-Distro Ubuntu？

在 Termux 中使用 proot-distro 运行 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 中。这意味着你可以两全其美：一个功能完整的 Ubuntu Linux 环境，同时仍能直接通过命令行访问 Android API（如相机、Toast、位置和传感器）。

功能（MCP 工具）

MCP 服务器提供了一整套工具来控制你的手机：

• 系统与硬件：

  • get_battery_status：读取设备电池电量、健康状态、温度和充电状态。

  • toggle_torch：打开或关闭手电筒/闪光灯。

  • 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：在手机屏幕上显示临时 Toast 通知。

  • vibrate_phone：让设备振动指定时长。

  • clipboard_get 和 clipboard_set：读取和写入 Android 剪贴板。

  • show_notification：显示标准 Android 通知。

  • prompt_user_dialog：在手机上显示交互式文本输入对话框，让你输入回复并返回给 AI 客户端。

  • share_text：将文本直接分享到 Android 的原生分享面板。

• 任意执行：

  • execute_command：直接在原生 Termux 宿主中运行任意 shell 命令。

详细的分步安装指南

第 1 步：在 Android 上安装 Termux 和 Termux:API

1. 安装 Termux 应用和 Termux:API 应用。

   • 必需： 从 F-Droid 安装这两个应用（不要混用 F-Droid 和 Play Store 版本，因为它们无法签名/绑定在一起）。

2. 前往 Android 设置 -> 应用 -> Termux:API -> 权限：

   • 授予相机、位置、短信、联系人和存储权限。

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 设置 -> Features -> MCP。

2. 点击 + Add New MCP Server。

3. 输入：

   • Name： termux-mcp

   • Type： SSE

   • URL： http://YOUR_PHONE_IP:8000/sse （复制粘贴服务器打印的 'SSE Connect URL'）

4. 点击 Save。

连接 Claude Desktop（通过 SSH 的替代 Stdio 方式）

如果你更喜欢通过 SSH 管道运行本地 stdio 命令，请参阅仓库文档中的选项 B，以设置 OpenSSH 密钥并配置你的本地 %APPDATA%\Claude\claude_desktop_config.json。

故障排除

• 工具调用挂起： 如果某个工具调用（如 get_location 或 take_photo）挂起，请检查 Termux:API 应用是否已在 Android 设置中授予权限，并确保电池节省模式已关闭。

• 连接被拒绝： 确保你的电脑和手机连接到同一个 Wi-Fi 网络，并且服务器正在运行。

• Termux 后台执行： Android 可能会在屏幕锁定时挂起 Termux 进程。下拉 Android 通知抽屉，确保 Termux 显示“1 session”并启用了“Acquire wake lock”，以保持其在后台运行。