Mobai Mcp

MobAI MCP 服务

适用于 MobAI 的 MCP（Model Context Protocol）服务 — AI 驱动的移动设备自动化工具。通过一个以 DSL 为先的接口，让 AI 助手（Claude Code、Cursor、Windsurf、Cline 及其他兼容 MCP 的工具）控制 Android 和 iOS 设备、模拟器及仿真器。

工作原理

所有设备交互都通过一个主要工具：execute_dsl 批量执行。服务不会暴露数十个细粒度工具（点按、滑动、输入等），而是接受一个 JSON 脚本，用于描述一系列包含谓词、断言、等待和条件分支的操作。这样可以减少往返调用次数，并在服务端编码重试和失败处理策略。

一小组配套工具用于发现设备、截取屏幕截图、管理应用，以及运行 .mob 测试文件。

前提条件

• Node.js 18+
• 本地运行的 MobAI 桌面应用（HTTP API 地址为 127.0.0.1:8686）
• 已连接的 Android 或 iOS 设备、模拟器或仿真器

安装

Claude Code

claude mcp add mobai -- npx -y mobai-mcp

Cursor

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "mobai": {
      "command": "npx",
      "args": ["-y", "mobai-mcp"]
    }
  }
}

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）：

{
  "mcpServers": {
    "mobai": {
      "command": "npx",
      "args": ["-y", "mobai-mcp"]
    }
  }
}

Windsurf / Cline / 其他 MCP 客户端

服务通过 stdio 通信 — 使用客户端通用的 MCP 配置：

{
  "command": "npx",
  "args": ["-y", "mobai-mcp"]
}

工具

设备管理

工具	描述
list_devices	列出所有已连接的 Android 和 iOS 设备
get_device	获取特定设备的详细信息
start_bridge	在设备上启动自动化桥接（交互前必需）
stop_bridge	停止自动化桥接
claim_device	为此会话独占占用设备（通常可选：操作未被占用的设备时会自动占用）
release_device	释放此会话持有的一个或所有设备租约

屏幕截图

工具	描述
get_screenshot	用于大模型视觉分析的快速低质量屏幕截图（可能会缩小尺寸；响应中包含缩放比例）
save_screenshot	将完整质量的 PNG 保存到磁盘，用于报告、调试或分享

应用

工具	描述
list_apps	列出设备上已安装的应用
install_app	从本地文件路径安装 .apk 或 .ipa
uninstall_app	根据 bundle ID / package name 卸载应用
debug_app	以调试模式启动应用，并将 stdout/stderr 写入日志文件

自动化

工具	描述
execute_dsl	主要工具。 批量执行 DSL 步骤：点按、输入、滑动、观察、断言、Web 自动化、指标、屏幕录制等。

测试管理

测试是存放在项目目录中的 .mob 文件。你可以直接使用助手的文件系统工具读取、编写和编辑这些文件 — MobAI 会监控更改并实时更新 UI。只有在发现项目和运行测试时才需要 MCP。

工具	描述
test_get_active	获取当前活动的测试项目目录及其 .mob 测试用例
test_list_projects	列出所有已知测试项目目录及其 .mob 测试用例
test_run	在设备上运行 .mob 测试用例（project_dir + case_path + device_id，可选 params 用于 ${name} 替换）

资源

在尝试进行任何设备交互之前，请先阅读这些内容 — 它们介绍 DSL 架构、操作集、谓词、失败处理策略和 .mob 语法。

URI	用途
mobai://reference/device-automation	如何控制设备 — 指南、所有 DSL 操作、谓词和失败处理策略
mobai://reference/testing	测试工作流、规则、错误修复和 .mob 脚本语法

示例

打开 iOS 设置应用，进入 Wi-Fi，并确认开关存在：

{
  "version": "0.2",
  "steps": [
    {"action": "open_app", "bundle_id": "com.apple.Preferences"},
    {"action": "wait_for", "predicate": {"text": "Settings"}, "timeout_ms": 3000},
    {"action": "tap", "predicate": {"text_contains": "Wi-Fi"}},
    {"action": "wait_for", "predicate": {"type": "switch"}, "timeout_ms": 3000},
    {"action": "assert_exists", "predicate": {"type": "switch"}},
    {"action": "observe", "include": ["ui_tree"]}
  ]
}

将其作为 JSON 字符串传入 execute_dsl 的 commands 参数，并同时传入来自 list_devices 的 device_id。

故障排查

“Connection refused” / “Could not reach the MobAI desktop app” — 确保已安装并运行 MobAI 桌面应用，且可通过 http://127.0.0.1:8686 访问 API。如果尚未安装，请从 https://mobai.run/download 下载并安装。

“Bridge not running” — 请先调用 start_bridge。iOS bridge 最多可能需要一分钟才能启动。

无法查看截图 — get_screenshot 默认将截图保存到 /tmp/mobai/screenshots/，并返回文件路径。使用助手的文件读取功能查看截图。DSL observe 截图会从响应中提取并保存到同一目录。

开发

git clone https://github.com/MobAI-App/mobai-mcp.git
cd mobai-mcp
npm install
npm run build
node dist/index.js

许可证

Apache 2.0 — 详见 LICENSE。