AutoBot MCP

Python Version MCP 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. 克隆仓库

git clone https://github.com/yourusername/autobot-mcp.git
cd autobot-mcp

1. 安装依赖

uv sync

1. 配置设备

创建配置文件（从示例复制）：

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 支持两种坐标系统：

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 文档
• MCP Python SDK
• Model Context Protocol
• AutoBot 项目