MobAI MCP Server

MCP (Model Context Protocol) server for MobAI — AI-powered mobile device automation. Lets AI assistants (Claude Code, Cursor, Windsurf, Cline, and other MCP-compatible tools) control Android and iOS devices, emulators, and simulators via a single DSL-first interface.

How it works

All device interaction is batched through one primary tool: execute_dsl. Instead of exposing dozens of fine-grained tools (tap, swipe, type…), the server accepts a JSON script describing a sequence of actions with predicates, assertions, waits, and conditional branches. This keeps round-trips low and encodes retry/failure strategies server-side.

A small set of companion tools handles device discovery, screenshots, app management, and running .mob test files.

Prerequisites

Node.js 18+
MobAI desktop app running locally (HTTP API on 127.0.0.1:8686)
A connected Android or iOS device, emulator, or simulator

Installation

Claude Code

Terminal

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

Cursor

Add to .cursor/mcp.json:

config.json

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

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

config.json

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

Windsurf / Cline / other MCP clients

The server speaks stdio — use your client's generic MCP configuration:

config.json

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

Tools

Device management

Tool	Description
`list_devices`	List all connected Android and iOS devices
`get_device`	Get details about a specific device
`start_bridge`	Start the automation bridge on a device (required before interaction)
`stop_bridge`	Stop the automation bridge
`claim_device`	Claim exclusive use of a device for this session (usually optional: acting on an unclaimed device auto-claims it)
`release_device`	Release one or all device leases held by this session

Screenshots

Tool	Description
`get_screenshot`	Fast, low-quality screenshot for LLM visual analysis (may be downscaled; response includes scale factor)
`save_screenshot`	Full-quality PNG to disk for reporting, debugging, or sharing

Apps

Tool	Description
`list_apps`	List installed apps on the device
`install_app`	Install an `.apk` or `.ipa` from a local file path
`uninstall_app`	Uninstall an app by bundle ID / package name
`debug_app`	Launch an app in debug mode and write stdout/stderr to a log file

Automation

Tool	Description
`execute_dsl`	Primary tool. Execute a batch of DSL steps: tap, type, swipe, observe, assertions, web automation, metrics, screen recording, and more.

Test management

Tests are .mob files on disk inside project directories. You read, write, and edit them directly using your assistant's filesystem tools — MobAI watches for changes and updates the UI live. MCP is only needed to discover projects and run tests.

Tool	Description
`test_get_active`	Get the active test project directory and its `.mob` cases
`test_list_projects`	List all known test project directories with their `.mob` cases
`test_run`	Run a `.mob` test case on a device (`project_dir` + `case_path` + `device_id`, optional `params` for `${name}` substitution)

Resources

Read these before attempting any device interaction — they describe the DSL schema, action set, predicates, failure strategies, and .mob syntax.

URI	Purpose
`mobai://reference/device-automation`	How to control devices — guide, all DSL actions, predicates, and failure strategies
`mobai://reference/testing`	Testing workflow, rules, error fixes, and `.mob` script syntax

Example

Open the iOS Settings app, navigate to Wi-Fi, and verify the toggle exists:

config.json

{
  "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"]}
  ]
}

Pass this as the commands argument (a JSON string) to execute_dsl along with a device_id from list_devices.

Troubleshooting

"Connection refused" / "Could not reach the MobAI desktop app" — Make sure the MobAI desktop app is installed and running, and the API is reachable at http://127.0.0.1:8686. If you don't have it yet, download and install it from https://mobai.run/download.

"Bridge not running" — Call start_bridge first. The iOS bridge can take up to a minute to come up.

Screenshots not visible — get_screenshot saves to /tmp/mobai/screenshots/ by default and returns the file path. Use your assistant's file-reading capability to view them. DSL observe screenshots are extracted from the response and saved to the same directory.

Development

bash

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

License

Apache 2.0 — see LICENSE.