Skip to main content
Glama
Sign In
Android MCP Server

Android MCP Server

by wujie272
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

🤖 Termux MCP Server

让 AI 直接操控你的 Android 手机 — 120+ 工具的 MCP 服务，运行在 Termux 上

Version License Python PRs

基于 xlisp/termux-mcp-server 全面重构，采用 FastMCP 框架，分层加载、智能重试、安全门控。

✨ 亮点速览

特性

说明

🛠 120+ 工具

屏幕操控 · 文件管理 · 应用管理 · 通信 · 传感器 · 媒体 · 天气 · Shizuku · GitHub

📡 8 个 Resources

电池/设备/WiFi/蜂窝/存储/健康/传感器/前台 — 可直接订阅

📝 5 个 Prompts

健康巡检/取证分析/屏幕向导/崩溃调查/自动化操作 — 模板化工作流

🚀 分层加载

核心工具 0s → 常用 3s → 低频 10s，启动即用不等待

🔒 安全门控

只读模式 + Shell 开关，环境变量控制，零代码入侵

🧠 智能定位

按文本/ID/类名找元素，一次调用定位+点击+验证

🏗 三层特权

Shizuku (rish) 🥇 → ADB 🥈 → Direct (Termux) 🥉，自动降级，最高权限优先

Related MCP server: mobilerun-mcp

📡 快速开始

# 通过管理工具（推荐）
bash ~/mcp-manager.sh android

# 或直接运行
cd ~/mcp-servers/termux-mcp

# stdio 模式（适合 Claude Desktop 本地调用）
python3 server.py

# HTTP/SSE 模式（适合远程访问，端口 3000）
python3 http_server.py

# 健康检查
curl http://手机IP:3000/health

MCP 客户端配置

{
  "mcpServers": {
    "termux-mcp": {
      "type": "sse",
      "url": "http://192.168.1.102:3000/sse"
    }
  }
}

⚠️ 将 192.168.1.102 替换为手机实际 IP（可用 bash ~/mcp-manager.sh wifi-ip 查看）

🏗 架构设计

┌─────────────────────────────────────────────────────┐
│                   MCP Client                         │
│           (Claude Desktop / RikkaHub / Cursor)       │
└────────────────────┬────────────────────────────────┘
                     │ MCP Protocol (SSE / stdio)
                     ▼
┌─────────────────────────────────────────────────────┐
│              termux-mcp (FastMCP)                    │
│                                                       │
│  ┌─────────────────────────────────────────────┐     │
│  │  🚀 Layer 1: 核心工具 (0s)                    │     │
│  │  device_info · ui_automation · ui_smart      │     │
│  │  github · aggregation · prompts · resources  │     │
│  ├─────────────────────────────────────────────┤     │
│  │  ⏳ Layer 2: 常用工具 (3s)                    │     │
│  │  file_system · app_management               │     │
│  │  communication · system_control             │     │
│  ├─────────────────────────────────────────────┤     │
│  │  🐌 Layer 3: 低频工具 (10s)                  │     │
│  │  media · adb                                 │     │
│  └─────────────────────────────────────────────┘     │
│                                                       │
│  ┌─── 🔒 Security Gate ─────────────────────────┐   │
│  │  TERMUX_MCP_READONLY    → 禁止写入操作       │   │
│  │  TERMUX_MCP_ALLOW_SHELL → 禁止 Shell 执行    │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  ┌─── 🏗 Privilege Chain ───────────────────────┐   │
│  │  Shizuku (rish) 🥇 → ADB 🥈 → Direct 🥉   │   │
│  │  自动降级，最高权限优先                      │   │
│  └──────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
         │                  │                  │
         ▼                  ▼                  ▼
   ┌──────────┐    ┌──────────────┐    ┌────────────┐
   │ Termux:API│    │ Shizuku/rish │    │    ADB     │
   │ 传感器/相机│    │ 截图/UI dump │    │ 无线调试   │
   │ 短信/TTS  │    │ 输入注入     │    │ (备选)     │
   └──────────┘    └──────────────┘    └────────────┘

📡 MCP Resources — 设备数据源

Resources 是可订阅的声明式数据源，Client 可主动读取或订阅更新。

Resource

URI

说明

🔋 电池

device://battery

电量/温度/充电状态/电压/电流/健康度

📱 设备

device://info

型号/品牌/Android版本/SDK/内核/架构/运行时间

📶 WiFi

device://network/wifi

SSID/信号强度/速率/频段/IP

📡 蜂窝

device://network/telephony

运营商/网络类型/SIM状态/漫游

💾 存储

device://storage

总量/已用/剩余/使用率

🩺 健康

device://health

电池+WiFi+存储一键快照

🎯 传感器

device://sensors

可用传感器列表及数量

📌 前台

device://app/foreground

当前前台运行的 App

📝 MCP Prompts — 模板化工作流

5 个预定义工作流模板，Client 调用后 AI 自动执行多步骤任务：

Prompt

适用场景

执行流程

device_health_check

设备卡顿/发热/耗电快时排查

电池→健康→存储→网络→设备→前台 → 报告

app_forensic_audit

审计第三方 App 安全性

包信息→权限审计→内存→Activity→数据 → 审计报告

screen_interaction_wizard

多步骤 UI 自动操作

截图→识别→点击→验证(循环)

crash_investigation

App 闪退/系统异常排查

健康基线→内存→存储→近期变更 → 事故报告

automation_operator

签到/打卡等重复任务

拆解步骤→逐个执行→验证→报告

🛠 聚合工具

一次调用获取多维数据，告别多次轮询：

工具

说明

数据来源数

device_health()

🔥 设备健康报告 — 电池 + 存储 + 内存 + WiFi + CPU + 进程，7路异步并发

⚡ 7

analyze_app(pkg)

🔍 包信息 + 权限 + 内存 + Activity + 进程（全维度审计）

📋 5

screen_diagnostics()

📺 分辨率 + 方向 + 亮度 + 前台 + UI 节点统计

🖥️ 5

🔒 安全门系统

环境变量控制，无需改代码：

# 只读模式 — 禁止所有写入操作（截图/点击/发短信/删文件等）
TERMUX_MCP_READONLY=true

# Shell 控制 — 禁止 Shell/ADB 命令执行
TERMUX_MCP_ALLOW_SHELL=false

每个工具标注安全等级：

等级

标识

示例

⚡ 中风险

交互操作

tap_screen(), input_text(), swipe_screen()

🚨 高风险

数据变更

send_sms(), write_file(), force_stop_app()

🛠 全部工具一览（100+）

🧠 智能定位（8 个）

工具

说明

find_element(text)

按文本/ID/类名/描述查找 UI 元素，返回坐标和属性

click_by_text(text)

按文本查找并点击（不受布局变化影响，最稳健）

click_by_id(id)

按资源 ID 查找并点击

click_by_class(cls)

按类名（Button/Switch 等）查找并点击

wait_for_element(text)

等待元素出现（轮询，超时可配，适合异步加载）

get_foreground_app()

获取当前前台应用包名+Activity

get_ui_state(scale)

结构化界面状态 + 可选标注截图（一键到位）

dump_ui_with_screenshot(scale)

标注所有可交互元素的截图 + 完整元素列表

🖥️ UI 自动化（20 个）

工具

说明

dump_ui(mode)

UI 树分析（summary / full / json 三模式）

tap_screen(x, y)

精确点击指定坐标

long_press(x, y, ms)

长按（可设时长）

swipe_screen(x1,y1 → x2,y2)

滑动操作（可调速）

input_text(text)

输入 ASCII 文本

input_chinese_text(text)

输入中文/多语言文本（剪贴板+Paste 方案）

input_keyevent(keycode)

发送按键事件（3=Home / 4=Back / 26=Power / 66=Enter / 67=Del / 187=Recent）

go_home() / go_back()

主页 / 返回

open_recent_apps()

最近应用

screen_on() / screen_off()

亮屏 / 息屏

rotate_device(rot)

旋转屏幕（0=竖屏 / 1=横屏 / 2=反向竖屏 / 3=反向横屏）

expand_notifications()

下拉通知栏

expand_settings()

展开快捷设置面板

collapse_panels()

收起通知栏/设置面板

screen_record(secs)

录屏（最长 180s，可显示触摸点）

📱 设备信息（18 个）

工具

说明

get_battery_status()

电池电量/温度/充电状态/电压/电流/健康度

get_battery_health()

深度电池健康：循环次数/容量/电压（dumpsys）

get_wifi_info()

WiFi 连接详情（SSID/BSSID/信号/速率/频段/IP）

scan_wifi()

扫描附近 WiFi 热点

wifi_qr_code()

生成当前 WiFi 二维码（可扫码连接）

get_telephony_info()

蜂窝网络信息（运营商/4G/5G/SIM 状态/IMEI）

get_telephony_cell_info()

基站信息（CID/LAC/信号强度/ARFCN）

get_location(provider)

GPS 定位（gps/network/passive · 单次/持续/最近）

get_sensor_list()

列出所有可用传感器

read_sensor(name)

读取传感器实时数据

get_device_info()

全面设备信息（型号/Android 版本/内核/架构/运行时间）

get_screen_size()

屏幕分辨率

get_screen_brightness()

当前亮度（需 Shizuku/ADB）

set_screen_brightness(level)

设置亮度 0-255（需 Shizuku/ADB）

device_health_report()

MCP 服务健康状态（运行时间/PID/日志大小）

list_adb_devices()

列出所有 ADB 连接设备（USB + WiFi，含型号）

restart_android(reason)

重启 termux-mcp 服务（~2-3s 自愈）

📁 文件系统（15 个）

工具

说明

read_file(path)

读取文本文件（自动检测编码）

write_file(path, content)

写入文件（自动创建父目录）

edit_file(path, old, new)

文本替换编辑（支持 dry-run 预览）

file_editor(path, action, ...)

🔧 智能行级编辑 — 插入/删除/替换/正则/注释/撤销。预览 → 确认 → 备份 → 回滚全程保护

search_files(query)

🔍 统一搜索引擎：文件名(fd) + 内容(rg) + 元数据过滤 + 模糊匹配(fzf)

file_copy(source, dest)

复制文件/目录（自动防覆盖加后缀）

file_move(source, dest)

移动/重命名文件/目录

file_delete(path)

安全删除（先预览再确认，不可恢复）

file_trash(path)

移到回收站 ~/.trash/（可还原）

file_symlink(source, link)

创建符号链接

dir_create(path)

创建目录（mkdir -p 行为）

get_file_info(path)

文件元信息（大小/日期/权限）

list_directory(path)

列出目录内容

list_allowed_directories()

列出可访问的目录白名单

📦 应用管理（9 个）

工具

说明

list_installed_packages()

列出 Termux 已装包（dpkg）

list_android_packages(keyword)

列出 Android 应用（可关键词过滤）

list_running_apps()

运行中进程 + CPU + 内存占用

app_usage_stats(days)

应用使用统计（近 N 天）

open_app(package)

启动应用（MAIN intent → 已知 Activity → monkey，多级降级）

force_stop_app(package)

强制停止应用

get_current_app()

当前聚焦应用（包名+Activity）

analyze_app(package)

🔍 深度分析：包信息+权限+内存+Activity+进程

💬 通信（15 个）

工具

说明

list_sms(limit, type)

短信列表（inbox/sent/draft/all）

send_sms(number, msg)

发送短信（会产生实际费用）

list_contacts()

通讯录（姓名/电话/邮箱）

get_clipboard()

读取剪贴板（Termux:API → 内存回退）

set_clipboard(text)

写入剪贴板

clipboard_history(limit)

剪贴板历史记录

clipboard_history_clear()

清空历史

send_notification(title, msg)

发送通知（可振动）

dismiss_notification(id)

按 ID 移除通知

list_notifications()

列出所有活跃通知

show_toast(text)

显示 Toast 消息

🔊 系统控制（9 个）

工具

说明

get_volume()

查看所有音频流音量（music/ring/alarm/notification/system/call）

set_volume(stream, level)

设置音量（0-15）

toggle_torch(on)

手电筒开关

vibrate(ms, force)

震动（支持静音模式强制震动）

text_to_speech(text, lang)

文字转语音朗读（支持多语言）

get_fingerprint()

指纹认证

open_url(url)

浏览器打开 URL

📷 媒体（7 个）

工具

说明

take_photo(camera_id)

拍照（0=后置 / 1=前置）

get_camera_info()

可用相机列表及参数

list_photos(dir, limit)

列出照片文件（jpg/png/gif/webp/heic）

media_player(action, path)

媒体播放控制（play/pause/stop/info）

share_file(path)

分享文件（系统分享面板）

download_file(url)

下载文件（系统下载管理器）

🌤️ 天气（5 个）

工具

说明

get_weather(city)

详细天气：温度/湿度/风速/气压 + 未来 3 天预报

get_weather_short(city)

一句话快速获取当前天气概况（支持城市名或坐标）

get_weather_by_coords(lat, lng)

通过 GPS 经纬度精准查天气

get_air_quality(city)

空气质量指数 AQI + PM2.5/PM10/O₃ 等污染物

🔌 ADB（2 个）

工具

说明

adb_status()

ADB/Shizuku 安装和连接状态诊断

adb_connect(pair_code, ports)

Android 12+ 无线调试配对连接

🎭 Shizuku 管理（6 个）

工具

说明

shizuku_status()

查看 Shizuku 全面状态：App 进程/守护进程/rish 可用性/小窗位置

shizuku_hide()

隐藏 Shizuku 小窗（缩到右上角极小尺寸 + force-stop UI）

shizuku_show()

显示/启动 Shizuku App 窗口

shizuku_resize(l,t,r,b)

调整小窗位置和大小（可从全屏到小点自由控制）

shizuku_restart()

重启 Shizuku App（卡死时恢复，守护进程不受影响）

💻 GitHub（10 个）

工具

说明

github_repo(owner, repo)

仓库详情（Star/Fork/描述/许可证）

github_list_repos(username)

列出用户仓库

github_search(query, type)

搜索仓库/代码/Issue

github_get_file(owner, repo, path)

读取文件或列目录

github_list_issues(owner, repo)

列出 Issue

github_repo_languages(owner, repo)

编程语言占比

github_list_branches(owner, repo)

列出分支

github_refresh_token()

手动刷新 GitHub Token

⚙️ 依赖

依赖

用途

安装方式

Termux:API

电池/WiFi/传感器/相机/短信/TTS/剪贴板

pkg install termux-api + 安装 Termux:API App

Shizuku 🥇

截图/UI dump/录屏/输入注入（推荐）

Shizuku 官网 开启 + 将 rish 放入 $HOME

ADB 🥈

Shizuku 不可用时的降级方案

pkg install android-tools + 开启无线调试

Pillow

截图劣化/标注截图

pip install Pillow

特权配置

# 方案 A：Shizuku（推荐）
# 1. 安装 Shizuku App 并授权
# 2. 确保 ~/rish 文件存在且可执行
# 3. 服务自动检测，无需额外配置

# 方案 B：ADB 无线调试（备选）
# 1. 开启 开发者选项 → 无线调试
# 2. adb connect 192.168.1.102:5555
# 3. adb devices 确认连接

🏗️ 项目结构

termux-mcp/
├── server.py                    # 🚀 stdio 入口
├── http_server.py               # 🌐 HTTP/SSE 入口（端口 3000）
├── http_termux_server.py        # 🔄 HTTP 兼容版
├── pyproject.toml               # 📦 项目配置（v0.4.0）
├── diagnose.sh                  # 🔧 环境诊断脚本
├── keepalive.sh                 # ♻️ 保活监控（30s 自愈）
├── _scan_tools.py               # 📋 工具扫描
└── termux_mcp/                 # 🧠 核心代码
    ├── __init__.py              # 包入口
    ├── __main__.py              # python -m 支持
    ├── app.py                   # FastMCP 实例 + 分层加载策略
    ├── prompts.py               # 📝 5 个 Prompt 模板
    ├── resources.py             # 📡 8 个 Resource 数据源
    ├── lib/
    │   ├── constants.py         # 📌 集中路径常量
    │   ├── utils.py             # 🔧 命令执行 + 日志轮转 + 安全门
    │   └── adb.py               # 🔌 ADB 连接管理
    └── tools/
        ├── aggregation.py       # 🔥 聚合工具（device_health 等 3 个）
        ├── ui_smart.py          # 🧠 智能元素定位（find/click by text 等）
        ├── ui_automation.py     # 🖥️ 截图/点击/输入/屏幕控制（20 个）
        ├── device_info.py       # 📱 设备信息（18 个）
        ├── file_system.py       # 📁 文件操作（15 个，含 file_editor）
        ├── app_management.py    # 📦 应用管理（9 个）
        ├── communication.py     # 💬 通信（15 个）
        ├── system_control.py    # 🔊 系统控制（9 个）
        ├── media.py             # 📷 相机/媒体（7 个）
        ├── weather.py           # 🌤️ 天气（5 个）
        ├── shizuku.py           # 🎭 Shizuku 管理（6 个）
        ├── adb.py               # 🔌 ADB 工具（2 个）
        └── github.py            # 💻 GitHub（10 个）

🔧 环境变量

变量

默认值

说明

TERMUX_MCP_READONLY

false

设为 true 禁止所有写入操作

TERMUX_MCP_ALLOW_SHELL

true

设为 false 禁止 Shell 命令执行

HOST

0.0.0.0

HTTP 服务监听地址

PORT

3000

HTTP 服务监听端口

🩺 健康检查

HTTP 模式下提供 /health 端点：

curl http://localhost:3000/health

# 返回:
# {
#   "status": "ok",
#   "service": "termux-mcp",
#   "uptime_sec": 3600,
#   "uptime_str": "1h 0m 0s",
#   "version": "0.2.0"
# }

保活监控脚本 keepalive.sh 每 30 秒轮询一次，服务挂了自动拉起，与内部重启形成「双层保险」。

❓ 常见问题

工具执行失败？

# 运行诊断脚本
cd ~/mcp-servers/termux-mcp && bash diagnose.sh

Shizuku 连接失败？

# 检查 rish 是否存在
ls -la ~/rish

# 测试 rish 连通性
~/rish -c "echo ok"

截图/点击不生效？

确保 Shizuku 或 ADB 已连接：

# 检查特权状态
bash ~/mcp-manager.sh status

# 测试截屏
screencap -p /sdcard/test.png && ls -la /sdcard/test.png

端口被占用？

lsof -i :3000

📄 许可

MIT — 基于 xlisp/termux-mcp-server

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    This server cannot be deployed

    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • scrcpy-mcp

      beatriz4020
      A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to visually perceive and directly control Android devices via ADB and screen-control tooling, including screenshots, taps, swipes, typing, app management, UI inspection, file transfer, shell commands, and audio/video streaming.
      374 npm
      MIT

    • scrcpy-mcp

      Thomas58834
      A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to see and control Android devices through ADB and scrcpy, supporting screenshots, input, app management, UI automation, shell/file access, and audio/video streaming.
      374 npm
      MIT