Skip to main content
Glama
MobAI MCP Server

MobAI MCP Server

Official
by MobAI-App

MobAI MCP Server

npm version License

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-mcp

Cursor

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_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:

{
  "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.js

License

Apache 2.0 — see LICENSE.

Available Tools

20 tools
debug_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

    A3.7/5.0

    Scored across 20 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness5/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      Enables 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.
      32
      10,260 npm
      519
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to control mobile and desktop devices with natural language, including running automation tasks, taking screenshots, and managing devices.
      6
      5 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      39
      55,827 npm
      Apache 2.0
    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      18
      4
      MIT