📱 phone-mcp-server

English | 中文说明

English

Turn your Android phone into an MCP server for AI assistants — powerful shell and device integration via Termux.

Built on the Model Context Protocol (MCP), this server allows AI assistants (like Claude Desktop, Cursor, GitHub Copilot CLI, etc.) to securely interact with your Android device running Termux.

✨ Features

• Full Termux Environment: Executes commands within Termux's native environment (/data/data/com.termux/files/usr/bin), retaining path resolution and shell behavior.

• Robust Shell Tool:

  • Configurable timeouts (default: 60s).

  • Smart output truncation (protecting client context from massive terminal dumps).

  • Detailed runtime execution profiling and exit-code reporting.

• MCP Streamable HTTP Transport: Modern HTTP transport supporting multi-session MCP clients.

• Service Management: Includes restart.sh helper script for easy background lifecycle management.

📋 Prerequisites

• Android Phone

• Termux installed from F-Droid

• Node.js: pkg install nodejs-lts

🚀 Quick Start

1. Installation

git clone https://github.com/mgyanik/phone-mcp-server.git
cd phone-mcp-server
npm install

2. Running the Server

Start in foreground:

node server.js

Or run in background / restart:

chmod +x restart.sh
./restart.sh

3. MCP Client Configuration

Add to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "phone": {
      "url": "http://<PHONE_IP>:3000/mcp"
    }
  }
}

Replace <PHONE_IP> with your phone's Wi-Fi IP address (displayed in server console output).

Related MCP server: sully-termux-mcp

中文说明

将你的 Android 手机打造成面向 AI 助手的 MCP 服务端 —— 通过 Termux 提供强大的 Shell 与设备控制能力。

本项目基于 Model Context Protocol (MCP)，让 AI 编程助手（如 Claude Desktop、Cursor、GitHub Copilot CLI 等）能够直接与运行 Termux 的安卓设备无缝交互。

✨ 功能特点

• 原生 Termux 运行环境：自动注入 Termux 环境变量与 $PREFIX/bin 路径，完整保留 Termux 终端生态与工具链支持。

• 增强型 Shell 工具：

  • 支持可配置超时控制（默认 60 秒）。

  • 智能长输出折叠截断（避免命令输出过长刷屏撑爆 AI 上下文窗口）。

  • 精确记录并展示每条命令的耗时和执行状态。

• MCP Streamable HTTP 协议：基于官方标准 HTTP 传输协议，支持多客户端会话管理。

• 便捷启停脚本：附带 restart.sh，支持一键热重载与后台静默运行。

📋 准备工作

• 安卓手机（Android 设备）

• Termux（推荐从 F-Droid 下载安装）

• Node.js 环境：pkg install nodejs-lts

🚀 快速上手

1. 安装项目

git clone https://github.com/mgyanik/phone-mcp-server.git
cd phone-mcp-server
npm install

2. 启动服务

前台运行：

node server.js

或者使用重载脚本后台启动：

chmod +x restart.sh
./restart.sh

3. 配置 MCP 客户端

在你的客户端配置（如 claude_desktop_config.json）中添加：

{
  "mcpServers": {
    "phone": {
      "url": "http://<手机局域网IP>:3000/mcp"
    }
  }
}

将 <手机局域网IP> 替换为你手机当前的 Wi-Fi IP 地址（服务启动日志会打印具体地址）。

📄 License

MIT — see LICENSE.