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

1. 安装依赖

1. 配置设备

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

编辑 config.yaml，填入你的设备信息：

运行服务器

方式一：使用 autobot-mcp 命令

方式二：直接运行 Python 脚本

方式三：激活虚拟环境后运行

📖 使用示例

Claude Code

添加 AutoBot MCP 服务器：

在项目目录下执行：

说明：

• --transport stdio：指定使用 stdio 传输方式

• autobot-mcp：服务器名称（可自定义）

• uv run autobot-mcp：启动命令，确保在项目目录下执行以正确加载 config.yaml

注意事项：

• 确保已创建并配置 config.yaml 文件

• 命令需要在项目根目录执行，以便找到配置文件

• 如果使用虚拟环境，也可以使用 python main.py 作为启动命令

测试连接

使用 autobot-mcp 命令测试：

使用 Python 脚本测试：

Python API 使用

🛠️ 可用工具函数

设备信息

• 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 项目