AutoBot MCP
一个基于 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 服务
安装步骤
- 克隆仓库
git clone https://github.com/yourusername/autobot-mcp.git
cd autobot-mcp
- 安装依赖
uv sync
- 配置设备
创建配置文件（从示例复制）：
cp config.yaml.example config.yaml
编辑 config.yaml，填入你的设备信息：
device:
ip: "192.168.1.100" # 替换为你的设备IP地址
port: 18080 # 替换为你的设备端口
运行服务器
方式一：使用 autobot-mcp 命令
uv run autobot-mcp
方式二：直接运行 Python 脚本
uv run python main.py
方式三：激活虚拟环境后运行
# Windows
.venv\Scripts\activate
# Linux/Mac
source .venv/bin/activate
autobot-mcp
# 或者
python main.py
📖 使用示例
Claude Code
添加 AutoBot MCP 服务器：
在项目目录下执行：
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 命令测试：
uv run autobot-mcp
# MCP 服务器将在 stdio 上运行，等待来自 MCP 客户端的连接
使用 Python 脚本测试：
uv run python -c "from main import hello; print(hello())"
Python API 使用
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 - 项目开发指南和完整工具文档
- USAGE.md - 命令行工具使用说明
- docs/autobot_http_api.md - AutoBot HTTP API 详细文档
- docs/prompts.md - 设备操作最佳实践
🎯 坐标系统
AutoBot MCP 支持两种坐标系统：
- 绝对坐标：直接使用像素值，如
x=300, y=500 - 百分比坐标：使用 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