# AutoBot MCP
[Python Version](https://www.python.org/downloads/)
[MCP](https://modelcontextprotocol.io/)
[License](LICENSE)
一个基于 AutoBot API 的 MCP（Model Context Protocol）服务器实现，用于远程控制和自动化 Android 设备。
## ✨ 功能特点
AutoBot MCP 提供了全面的 Android 设备控制功能，包括：
### 📱 设备信息获取
- 获取已安装应用列表
- 获取设备详细信息（硬件、系统、内存、存储）
- 获取屏幕信息和截图
- 获取 UI 布局（JSON/XML 格式）
### 🎮 设备控制
- 点击、长按、滑动等触摸操作
- 文本输入和按键模拟
- 手势操作（单指/多指）
- 屏幕亮灭控制和录屏
- **智能屏幕常亮**（自动保持屏幕常亮，操作结束后恢复）
### 📲 应用管理
- 启动和停止应用
- 获取应用信息
- 清除应用数据
### 📞 通信功能
- 联系人管理（增删查）
- 短信管理（收发）
- 电话拨打和挂断
### 📁 文件操作
- 文件列表和删除
- 文件上传下载
### 🔧 系统操作
- 执行 ADB Shell 命令
- 剪切板操作
- 脚本执行（AutoX.js）
## 🚀 快速开始
### 环境要求
- **Python**: >= 3.12
- **uv**: 最新版本的 Python 包管理器
- **Android 设备**: 运行 AutoBot HTTP 服务
### 安装步骤
1. **克隆仓库**
```bash
git clone https://github.com/yourusername/autobot-mcp.git
cd autobot-mcp
```
1. **安装依赖**
```bash
uv sync
```
1. **配置设备**
创建配置文件（从示例复制）：
```bash
cp config.yaml.example config.yaml
```
编辑 `config.yaml`，填入你的设备信息：
```yaml
device:
ip: "192.168.1.100" # 替换为你的设备IP地址
port: 18080 # 替换为你的设备端口
```
### 运行服务器
**方式一：使用 autobot-mcp 命令**
```bash
uv run autobot-mcp
```
**方式二：直接运行 Python 脚本**
```bash
uv run python main.py
```
**方式三：激活虚拟环境后运行**
```bash
# Windows
.venv\Scripts\activate
# Linux/Mac
source .venv/bin/activate
autobot-mcp
# 或者
python main.py
```
## 📖 使用示例
### Claude Code
**添加 AutoBot MCP 服务器：**
在项目目录下执行：
```bash
claude mcp add --transport stdio autobot-mcp -- \
uv run --directory /path/to/autobot-mcp autobot-mcp
```
**说明：**
- `--transport stdio`：指定使用 stdio 传输方式
- `autobot-mcp`：服务器名称（可自定义）
- `uv run autobot-mcp`：启动命令，确保在项目目录下执行以正确加载 `config.yaml`
**注意事项：**
- 确保已创建并配置 `config.yaml` 文件
- 命令需要在项目根目录执行，以便找到配置文件
- 如果使用虚拟环境，也可以使用 `python main.py` 作为启动命令
### 测试连接
**使用 autobot-mcp 命令测试：**
```bash
uv run autobot-mcp
# MCP 服务器将在 stdio 上运行，等待来自 MCP 客户端的连接
```
**使用 Python 脚本测试：**
```bash
uv run python -c "from main import hello; print(hello())"
```
### Python API 使用
```python
from main import mcp
# 设备已连接后，可以使用各种工具
# 获取设备信息
device_info = get_device_info()
# 启动应用
start_app("com.android.chrome")
# 点击屏幕
click(0.5, 0.5) # 点击屏幕中心（百分比坐标）
# 获取截图
screenshot = get_screenshot()
```
## 🛠️ 可用工具函数
### 设备信息
- `get_packages()` - 获取所有已安装应用
- `get_device_info()` - 获取设备详细信息
- `get_screen_info()` - 获取屏幕信息
- `get_screenshot()` - 获取设备截图
- `get_uilayout()` - 获取当前 UI 布局
- `hello()` - 测试服务器连接
### 屏幕操作
- `click(x, y)` - 点击屏幕（支持百分比和绝对坐标）
- `long_click(x, y)` - 长按屏幕
- `swipe(x1, y1, x2, y2, duration)` - 滑动操作
- `input_text(text)` - 输入文本（支持多语言）
- `press_key(key_code)` - 模拟按键
- `gesture(duration, points)` - 单指手势
- `gestures(gestures_data)` - 多指手势
### 应用管理
- `start_app(package_name)` - 启动应用
- `stop_app(package_name)` - 停止应用
- `get_package_action_intents(package_name)` - 获取应用信息
- `clear_app_data(package_name)` - 清除应用数据
### 系统操作
- `execute_adb_shell_command(command)` - 执行 ADB 命令
- `turn_screen_on()` - 亮屏
- `turn_screen_off()` - 熄屏
- `start_screen_recording(limit)` - 开始录屏
- `stop_screen_recording()` - 停止录屏
### 通信功能
- `get_contacts(number)` - 获取联系人
- `send_sms(phone_number, message)` - 发送短信
- `call_phone(number)` - 拨打电话
- `get_clipboard_text()` - 获取剪切板内容
- `set_clipboard_text(text)` - 设置剪切板内容
### 文件操作
- `list_files(path)` - 列出文件
- `delete_file(path)` - 删除文件
- `get_file_url(path)` - 获取文件下载链接
## 📚 文档
- **[CLAUDE.md](CLAUDE.md)** - 项目开发指南和完整工具文档
- **[USAGE.md](USAGE.md)** - 命令行工具使用说明
- **[docs/autobot_http_api.md](docs/autobot_http_api.md)** - AutoBot HTTP API 详细文档
- **[docs/prompts.md](docs/prompts.md)** - 设备操作最佳实践
## 🎯 坐标系统
AutoBot MCP 支持两种坐标系统：
1. **绝对坐标**：直接使用像素值，如 `x=300, y=500`
2. **百分比坐标**：使用 0-1 之间的浮点数，如 `x=0.5, y=0.5`（屏幕正中心）
**推荐使用百分比坐标**以提高跨设备兼容性。
## ⚠️ 注意事项
### 设备状态
- 执行操作前确保设备处于亮屏和解锁状态
- 参考文档了解屏幕状态检查方法
### 安全警告
- `delete_contact()` 和 `clear_app_data()` 等操作不可恢复
- `exit_service()` 会终止 AutoBot 服务
- 执行脚本时注意权限和安全性
### 性能建议
- 避免频繁调用 `get_screenshot()`，图像传输开销较大
- 批量操作时考虑使用 ADB 命令
- 使用百分比坐标提高兼容性
## 🔧 故障排除
### 连接失败
- 检查设备 IP 地址和端口是否正确
- 确保设备和电脑在同一网络
- 确认 AutoBot 服务正在设备上运行
### 配置问题
- 确保已创建 `config.yaml` 文件
- 检查配置文件格式是否正确
### 操作无响应
- 检查设备是否亮屏和解锁
- 确认应用包名是否正确
- 查看错误信息了解具体问题
## 🤝 贡献
欢迎提交 Issue 和 Pull Request！
## 📄 许可证
MIT License
## 🔗 相关链接
- [FastMCP 文档](https://gofastmcp.com/)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [AutoBot 项目](https://github.com/yourusername/autobot)
