# zero-termux-mcp

**Repository Path**: goodboy-admin/zero-termux-mcp

## Basic Information

- **Project Name**: zero-termux-mcp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-13
- **Last Updated**: 2026-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Zero Termux MCP

Termux MCP 服务器 - 在 Android 手机上运行 AI 工具服务器

![Python](https://img.shields.io/badge/Python-3.8%2B-blue)
![License](https://img.shields.io/badge/License-MIT-green)
![Platform](https://img.shields.io/badge/Platform-Termux-orange)
![Tools](https://img.shields.io/badge/Tools-123-brightgreen)
![Tests](https://img.shields.io/badge/Tests-446%2F446-passing-brightgreen)

## 简介

Zero Termux MCP 是一个基于 Model Context Protocol (MCP) 的服务器实现，专为 Termux 环境设计。它让你能够在 Android 手机上运行一个功能完整的 AI 工具服务器，提供 **123 个工具**，覆盖文件操作、系统管理、网络查询、设备控制、传感器、多媒体、短信、联系人、应用管理、系统监控、文件管理、网络高级操作、数据加密等全方位功能。

### 核心特性

| 特性 | 说明 |
|------|------|
| 123 个工具 | 覆盖文件、系统、网络、设备控制、传感器、多媒体、短信、联系人、应用管理、系统监控、文件管理、网络高级操作、数据加密 |
| 智能缓存 | 路径缓存 5 分钟，命令缓存 60 秒，支持磁盘持久化 |
| 安全可靠 | 危险命令拦截 + 路径边界检查 + Shell 注入防护 + 变量名白名单 |
| 高性能 | 并行执行，asyncio 异步架构 |
| 优雅退出 | Ctrl+C 安全停止，自动保存缓存 |
| 完整测试 | 446 个单元测试，覆盖率核心功能 |

---

## 快速开始

### 1. 环境准备

```bash
pkg update && pkg upgrade
pkg install python python-cryptography
pip install "mcp>=2"
python -c "from mcp.server.mcpserver import MCPServer; print('OK')"
```

### 2. 克隆并运行

```bash
git clone https://gitee.com/goodboy-admin/zero-termux-mcp.git
cd zero-termux-mcp
python3 -m termux_mcp
```

### 3. 一键脚本

```bash
curl -sL https://gitee.com/goodboy-admin/zero-termux-mcp/raw/main/scripts/start.sh | bash
```

---

## 工具列表

### 核心工具

| 工具 | 功能 | 参数 | 缓存 |
|------|------|------|------|
| run_command | 执行 Shell 命令 | command, timeout, workdir, use_cache | 是 |
| list_dir | 列出目录内容 | path, detailed | 是 |
| read_file | 读取文件内容 | path, line_start(>=1), line_end | 是 |
| write_file | 写入文件内容 | path, content, append | 是 |

### 系统工具

| 工具 | 功能 | 缓存 | 并行 |
|------|------|------|------|
| sys_info | 获取系统信息 | 是 | 是 |
| battery_status | 电池状态 | 是 | 否 |
| get_device_info | 设备信息 | 是 | 是 |
| get_storage_info | 存储信息 | 是 | 是 |

### 系统服务

| 工具 | 功能 |
|------|------|
| send_notification | 发送系统通知 |
| clip_get | 获取剪贴板内容 |
| clip_set | 设置剪贴板内容 |
| speak_text | 语音播报 |
| get_location | 获取位置信息 |

### 搜索与网络

| 工具 | 功能 | 缓存 | 并行 |
|------|------|------|------|
| file_search | 搜索文件内容 | 是 | 否 |
| network_info | 网络状态 | 是 | 是 |

### 系统管理

| 工具 | 功能 |
|------|------|
| install_package | 通过 pkg 安装软件包 |
| list_installed_packages | 列出已安装软件包 |
| process_list | 查看运行中的进程 |
| process_kill | 终止进程 |
| check_disk_usage | 检查磁盘使用量 |
| env_get | 获取环境变量 |
| terminal_resize | 调整终端大小 |

### 缓存管理

| 工具 | 功能 |
|------|------|
| clear_cache | 清除所有缓存 |
| cache_stats | 查看缓存统计 |

---

## 安全特性

| 防护层 | 说明 |
|--------|------|
| 危险命令拦截 | 19 条黑名单规则，拦截高危操作 |
| 路径边界检查 | 限制访问 home 目录及其子目录 |
| Shell 注入防护 | 使用 shlex.quote() 转义用户输入 |
| 变量名白名单 | env_get 仅允许合法变量名 |
| 优雅退出 | Ctrl+C 安全停止，自动保存缓存 |

---

## 项目结构

```
zero-termux-mcp/
├── termux_mcp/               # 主程序包
│   ├── __init__.py           # 模块入口
│   ├── config.py             # 配置管理
│   ├── cache.py              # 缓存系统
│   ├── security.py           # 安全模块
│   └── tools/                # 工具函数
├── tests/                    # 单元测试
├── scripts/                  # 辅助脚本
├── docs/                     # 文档
├── examples/                 # 示例代码
├── README.md
├── CHANGELOG.md
├── QUICKSTART.md
└── requirements.txt
```
---

## 运行方式

### 前台运行
```bash
python3 -m termux_mcp
```

### 后台运行
```bash
nohup python3 -m termux_mcp > mcp.log 2>&1 &
kill $(cat mcp.pid)
```
---

## 测试

```bash
python3 -m unittest discover -s tests -v
```
---

## 许可证

MIT License - 详见 LICENSE 文件。

---

**Made with love in Termux**