MobAI MCP Server
OfficialThe MobAI MCP Server enables AI assistants to automate and interact with Android/iOS devices, emulators, and simulators through a DSL-first interface. Key capabilities include:
Device Management: List connected devices, get details, start/stop automation bridges, and claim/release exclusive device leases.
Screenshots: Capture low-quality screenshots for AI analysis (with scale factor) and save full-quality PNGs to disk.
App Management: List, install, uninstall, and launch apps in debug mode with log capture.
Automation: Execute DSL scripts (
execute_dsl) for complex interactions (tap, swipe, type, observe, assert, web automation, conditional branches, retry/failure strategies, screen recording).Test Management: Get active test project, list all projects, and run
.mobtest cases on a device with optional parameter substitution.iOS Debugging: Attach to apps (by bundle ID or PID), set breakpoints, evaluate Swift/ObjC expressions, step through code, and manage debug sessions.
Resource Access: Retrieve reference documentation for DSL, predicates, failure strategies, and testing workflows via MCP resources.
Provides tools for automating Android devices, emulators, and simulators, including actions like tap, type, swipe, screenshot, app management, and assertion-based automation.
Provides tools for automating iOS devices and simulators, including actions like tap, type, swipe, screenshot, app management, and assertion-based automation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MobAI MCP Server Open the Settings app on my Android device and navigate to Wi-Fi"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: @qirabot/mcp
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
claude mcp add mobai -- npx -y mobai-mcpCursor
Add to .cursor/mcp.json:
{
"mcpServers": {
"mobai": {
"command": "npx",
"args": ["-y", "mobai-mcp"]
}
}
}Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):
{
"mcpServers": {
"mobai": {
"command": "npx",
"args": ["-y", "mobai-mcp"]
}
}
}Windsurf / Cline / other MCP clients
The server speaks stdio — use your client's generic MCP configuration:
{
"command": "npx",
"args": ["-y", "mobai-mcp"]
}Tools
Device management
Tool | Description |
| List all connected Android and iOS devices |
| Get details about a specific device |
| Start the automation bridge on a device (required before interaction) |
| Stop the automation bridge |
| Claim exclusive use of a device for this session (usually optional: acting on an unclaimed device auto-claims it) |
| Release one or all device leases held by this session |
Screenshots
Tool | Description |
| Fast, low-quality screenshot for LLM visual analysis (may be downscaled; response includes scale factor) |
| Full-quality PNG to disk for reporting, debugging, or sharing |
Apps
Tool | Description |
| List installed apps on the device |
| Install an |
| Uninstall an app by bundle ID / package name |
| Launch an app in debug mode and write stdout/stderr to a log file |
Automation
Tool | Description |
| 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 |
| Get the active test project directory and its |
| List all known test project directories with their |
| Run a |
Resources
Read these before attempting any device interaction — they describe the DSL schema, action set, predicates, failure strategies, and .mob syntax.
URI | Purpose |
| How to control devices — guide, all DSL actions, predicates, and failure strategies |
| Testing workflow, rules, error fixes, and |
Example
Open the iOS Settings app, navigate to Wi-Fi, and verify the toggle exists:
{
"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
git clone https://github.com/MobAI-App/mobai-mcp.git
cd mobai-mcp
npm install
npm run build
node dist/index.jsLicense
Apache 2.0 — see LICENSE.
Available Tools
20 toolsdebug_appA
Launch an app in debug mode and write logs to a file. Returns the log file path — use Read/Grep to inspect logs. Use kill_app to stop.
Inputs: device_id (required), bundle_id (required), log_path.
debug_attachA
Start a debug session for an iOS app. Provide either bundle_id (launches and attaches) or pid (attaches to a running process). Optional breakpoints[] are armed before the target resumes. Read mobai://reference/debugging first.
Inputs: device_id (required), bundle_id, pid, breakpoints, +1 more.
debug_breakpointA
Add or remove a breakpoint in the active debug session. For action=add provide spec; for action=remove provide id.
Inputs: device_id (required), action (required), spec, id.
debug_detachA
End the debug session. Pass kill=true to terminate the debuggee; otherwise it keeps running.
Inputs: device_id (required), kill.
debug_evalA
Evaluate a Swift/ObjC expression at the current pause. Session must be paused. Examples: "p defaultPrivate", "po self.viewModel.user.email", "frame variable".
Inputs: device_id (required), expression (required), frame_id.
debug_stateA
Query the current debug session. Returns {state, breakpoints} by default. Set include_stack=true to also fetch the stack of the stopped thread; include_vars=true to also fetch frame[0] locals; include_threads=true to enumerate all threads.
Inputs: device_id (required), include_stack, include_vars, include_threads.
debug_stepA
Advance the target. "in" — step into next call (blocks ~ms, returns {state, breakpoints, stack, frame0_locals}) "over" — step over next call (same shape) "out" — run until current frame returns (same shape) "continue" — resume until next breakpoint (fire-and-forget; returns just {state, breakpoints} — poll debug_state for next stop)
Inputs: device_id (required), direction (required), include_stack, include_vars.
execute_dslA
Execute a batch of DSL commands on a device. This is the primary tool for all device interaction — tap, type, swipe, observe, launch apps, assertions, web automation, and more.
You MUST read the MCP resource mobai://reference/device-automation to learn how to control devices before using this tool.
Input: JSON string with "version": "0.2" and "steps" array. Example: {"version":"0.2","steps":[ {"action":"open_app","bundle_id":"com.apple.Preferences"}, {"action":"tap","predicate":{"text_contains":"Wi-Fi"}}, {"action":"wait_for","predicate":{"type":"switch"},"timeout_ms":3000} ]}
Inputs: device_id (required), commands (required).
get_deviceB
Get details about a specific device
Inputs: device_id (required).
get_screenshotA
Capture a fast, low-quality screenshot for LLM visual analysis. Returns the file path to the saved image. The image may be downscaled by an integer factor so its long edge stays ≤ 2000px; when that happens the response includes a scale factor — multiply any coordinates you read off the image by that factor before using them in device actions (tap, swipe, drag, long-press, etc.). UI tree coordinates are already in device pixels, do not scale those. Use this for AI/LLM processing only — for full-quality screenshots use save_screenshot instead.
Inputs: device_id (required).
install_appA
Install an app on the device from a local file path (.apk for Android, .ipa for iOS)
Inputs: device_id (required), path (required).
list_appsA
List installed apps on the device
Inputs: device_id (required).
list_devicesA
List all connected Android and iOS devices
Inputs: no named parameters.
save_screenshotA
Save a full-quality PNG screenshot to disk. Use this when you need a high-quality image for reporting, debugging, or sharing — not for LLM processing (use get_screenshot instead).
Inputs: device_id (required), path, name.
start_bridgeA
Start the automation bridge on a device. Required before interacting with the device.
Inputs: device_id (required).
stop_bridgeC
Stop the automation bridge on a device
Inputs: device_id (required).
test_get_activeA
Get the currently active test project directory and its .mob test cases. Use this to discover the project path and available tests. The agent can then read/write/create/delete .mob files directly in the returned directory.
Inputs: no named parameters.
test_list_projectsA
List all known test project directories with their .mob test cases. Each project is a directory containing .mob script files.
Inputs: no named parameters.
test_runB
Run a .mob test case on a device. The case_path is relative to the project directory. Pass params to supply values for ${name} substitution in the script.
Inputs: project_dir (required), case_path (required), device_id (required), params.
uninstall_appB
Uninstall an app from the device
Inputs: device_id (required), bundle_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Each tool has a distinct purpose, with clear separation between debugging, device automation, screenshots, and test management. Only minor potential overlap between debug_app and debug_attach, but their descriptions clearly differentiate them.
Tools follow a consistent verb_noun pattern with snake_case, and use prefixes like debug_, test_ for grouping. Some variation exists (e.g., execute_dsl vs. start_bridge), but it is still predictable and readable.
20 tools is slightly above the typical range, but each tool serves a specific need in debugging, device automation, and testing. The count is justified by the breadth of functionality.
The tool set covers the full lifecycle for debugging (attach, breakpoints, step, eval, detach) and device automation (bridge management, DSL execution, screenshots, app management). Test management includes listing, running, and file-level operations. No obvious gaps.
Maintenance
Related MCP Connectors
Let AI agents control Android and iOS devices on Mobilerun Cloud: screen, input, apps, workflows.
Drive real Android & iOS devices and web browsers from natural language for mobile + web QA. 290+ tools across device control, app management, automation sessions, browser automation, and flow recording / replay. Bearer-auth — get a token at robotactions.com → Profile → API Tokens.
Give your AI agent a real cloud Android phone: push APKs, drive it, get screenshots and logs.
AI agents on real phones: run tasks, read the screen, tap, type and install apps.
Related MCP Servers
AlicenseAqualityAmaintenanceEnables AI assistants to automate mobile app testing and development for iOS and Android through natural language interactions. Supports intelligent element identification, session management, automated test generation, and comprehensive device interactions including clicks, swipes, screenshots, and app management.3210,260 npm519Apache 2.0- AlicenseAqualityBmaintenanceEnables AI assistants to control mobile and desktop devices with natural language, including running automation tasks, taking screenshots, and managing devices.65 npmMIT
- AlicenseAqualityCmaintenanceEnables agents and LLMs to interact with native iOS and Android applications and devices via structured accessibility snapshots or coordinate-based taps, supporting simulators, emulators, and real devices.3955,827 npmApache 2.0
- AlicenseBqualityBmaintenanceEnables AI agents to automate Android and iOS devices, including emulators and physical devices, by capturing screenshots, reading UI accessibility trees, performing touch and text input, and managing app lifecycle and logs.184MIT