使用说明

安卓MCP服务器

一个生产级的MCP（模型上下文协议）服务器，通过ADB、UIAutomator、Accessibility和Vision（截图）让任何AI代理完全控制Android设备。

特性

30+MCP工具 --设备控制、应用程序管理、UI自动化、视觉、测试
多设备支持 --同时控制多个Android设备
智能执行 --UI自动机→ 无障碍→ 视觉→ 协调回退
安全 --输入消毒、速率限制、设备分配、破坏性操作保护
自动化 --动作记录/回放、测试场景、状态跟踪
可观测性 --结构化JSON日志、每个工具的指标、操作历史

先决条件

Node.js ≥ 18
安卓调试桥 已安装并位于PATH上(Android SDK平台工具)
通过USB/WiFi连接的Android设备或模拟器

验证ADB是否正常工作：

adb devices

设置

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run the server
npm start

MCP客户端配置

克劳德桌面

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "android": {
      "command": "node",
      "args": ["repo_path/dist/mcp/server.js"],
      "env": {
        "ADB_PATH": "adb"
      }
    }
  }
}

光标

添加到光标MCP设置中：

{
  "mcpServers": {
    "android": {
      "command": "node",
      "args": ["repo_path/dist/mcp/server.js"]
    }
  }
}

通用MCP客户端（stdio）

node dist/mcp/server.js

服务器使用MCP JSON-RPC协议通过stdin/stdout进行通信。

配置

创建 android-mcp.config.json 在项目根目录中（可选）：

{
  "adbPath": "adb",
  "allowedDevices": [],
  "maxActionsPerMinute": 120,
  "commandTimeoutMs": 30000,
  "maxRetries": 3,
  "debug": false,
  "screenshotDir": "./screenshots",
  "recordingsDir": "./recordings",
  "allowDestructiveOps": false
}

或者使用环境变量：

变量	描述
`ADB_PATH`	adb二进制文件的路径
`ALLOWED_DEVICES`	逗号分隔的设备ID
`MAX_ACTIONS_PER_MINUTE`	每台设备的速率限制
`COMMAND_TIMEOUT_MS`	ADB命令超时
`MAX_RETRIES`	自动重试计数
`DEBUG`	启用调试日志记录
`ALLOW_DESTRUCTIVE_OPS`	允许卸载等。

可用工具

设备管理

工具	说明
`list_devices`	列出已连接的Android设备
`get_device_info`	获取设备型号、操作系统、屏幕尺寸
`get_screen_size`	获取屏幕分辨率

输入控件

工具	说明
`tap`	点击坐标
`swipe`	在点之间滑动
`long_press`	长按坐标
`double_tap`	双击坐标
`input_text`	在焦点字段中键入文本
`press_key`	按下硬件/软件键

应用程序管理

工具	说明
`list_apps`	列出已安装的应用程序
`open_app`	按程序包名称启动应用程序
`close_app`	强制停止应用程序
`install_apk`	安装APK文件
`uninstall_app`	卸载应用程序（需要配置）
`get_current_app`	获取前台应用程序包

文件系统

工具	说明
`list_files`	列出设备上的文件
`pull_file`	从设备下载文件
`push_file`	将文件上传到设备

UI自动化（UIAutomator）

工具	说明
`get_ui_tree`	捕获UI层次结构
`find_element`	按选择器查找元素
`click_element`	查找并单击元素
`wait_for_element`	等待元素出现
`assert_element_exists`	检查元素是否存在

视觉

工具	说明
`capture_screenshot`	捕获设备屏幕截图
`analyze_screen`	截图+UI树分析
`detect_elements_visually`	检测交互元素
`compare_screenshots`	检测屏幕变化

自动化与测试

工具	说明
`smart_click`	多策略元素点击
`run_test_scenario`	执行测试步骤
`start_recording`	开始录制操作
`stop_recording`	停止并保存录制
`replay_recording`	回放记录的操作
`list_recordings`	列出已保存的录音
`get_device_state`	获取设备状态摘要
`get_metrics`	获取性能指标

建筑

src/
├── mcp/
│   └── server.ts           # MCP server entry point
├── controllers/
│   ├── device-tools.ts      # Device MCP tools
│   ├── input-tools.ts       # Input MCP tools
│   ├── app-tools.ts         # App management MCP tools
│   ├── file-tools.ts        # File system MCP tools
│   ├── ui-tools.ts          # UIAutomator MCP tools
│   ├── vision-tools.ts      # Vision MCP tools
│   └── automation-tools.ts  # Automation MCP tools
├── adb/
│   ├── adb-executor.ts      # Safe ADB command execution
│   ├── device-manager.ts    # Device discovery & sessions
│   ├── input-controller.ts  # Touch/key input
│   ├── app-manager.ts       # App lifecycle
│   └── file-manager.ts      # File operations
├── uiautomator/
│   ├── ui-tree-parser.ts    # XML → JSON conversion
│   ├── element-finder.ts    # Element search & interaction
│   └── element-cache.ts     # LRU element cache
├── vision/
│   ├── screenshot.ts        # Screenshot capture
│   ├── screen-diff.ts       # Screenshot comparison
│   └── visual-analyzer.ts   # AI-ready screen analysis
├── accessibility/
│   ├── accessibility-bridge.ts  # Accessibility fallback
│   └── smart-executor.ts       # Multi-strategy executor
├── automation/
│   ├── action-recorder.ts   # Action recording
│   ├── action-replayer.ts   # Action replay
│   ├── test-runner.ts       # Test scenarios
│   └── state-tracker.ts     # Device state memory
├── security/
│   ├── validator.ts         # Input sanitization
│   └── rate-limiter.ts      # Rate limiting
└── utils/
    ├── logger.ts            # Structured logging
    ├── config.ts            # Configuration
    ├── errors.ts            # Error hierarchy
    ├── retry.ts             # Retry logic
    └── metrics.ts           # Performance tracking

测试

npm test
npm run test:coverage

发展

# Run in development mode (ts-node)
npm run dev

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/mcp/server.js

许可证

麻省理工学院