MobAI MCP Server

MCP (Model Context Protocol) server for MobAI - AI-powered mobile device automation. This server enables AI coding assistants like Cursor, Windsurf, Cline, and other MCP-compatible tools to control Android and iOS devices, emulators, and simulators.

Features

• Device Control: List, connect, and manage Android/iOS devices
• UI Automation: Tap, type, swipe, and interact with native apps
• Web Automation: Control Safari/Chrome and WebViews with CSS selectors
• DSL Batch Execution: Execute multiple automation steps efficiently
• AI Agent: Run autonomous agents to complete complex tasks
• Screenshot Capture: Capture and save device screenshots

Prerequisites

• Node.js 18+
• MobAI desktop app running locally (provides the HTTP API on port 8686)
• Connected Android or iOS device (or emulator/simulator)

Installation & Configuration

Cursor

Add to .cursor/mcp.json:

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

Claude Desktop

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

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

Windsurf

Add to Windsurf MCP config:

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

Cline / Other MCP Clients

Configure according to your client's MCP server setup. The server uses stdio transport.

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

Available Tools

Device Management

• list_devices - List all connected devices
• get_device - Get device information
• start_bridge - Start on-device automation bridge
• stop_bridge - Stop automation bridge

UI Automation

• get_screenshot - Capture device screenshot
• get_ui_tree - Get accessibility tree
• tap - Tap element by index or coordinates
• type_text - Type text
• swipe - Perform swipe gesture
• go_home - Navigate to home screen
• launch_app - Launch app by bundle ID
• list_apps - List installed apps

DSL Execution

• execute_dsl - Execute batch automation script

AI Agent

• run_agent - Run autonomous agent for complex tasks

Web Automation

• web_list_pages - List browser tabs/WebViews
• web_navigate - Navigate to URL
• web_get_dom - Get DOM tree
• web_click - Click element by CSS selector
• web_type - Type into element by CSS selector
• web_execute_js - Execute JavaScript

Low-Level

• http_request - Make raw HTTP request to MobAI API

Available Resources

• mobai://api-reference - Complete API documentation
• mobai://dsl-guide - DSL batch execution guide
• mobai://native-runner - Native app automation guide
• mobai://web-runner - Web automation guide

Example Usage

List devices and take screenshot

Use the list_devices tool to see connected devices.
Then use get_screenshot with the device ID.

Automate Settings app

Use execute_dsl with:
{
  "version": "0.2",
  "steps": [
    {"action": "open_app", "bundle_id": "com.apple.Preferences"},
    {"action": "delay", "duration_ms": 1000},
    {"action": "observe", "context": "native", "include": ["ui_tree"]},
    {"action": "tap", "predicate": {"text_contains": "General"}}
  ]
}

Run AI agent

Use run_agent with device_id and task: "Open Settings and enable WiFi"

Comparison with Claude Code Plugin

The MCP server provides the same functionality as the Claude Code plugin but works with any MCP-compatible AI tool.

Troubleshooting

"Connection refused" error

• Ensure MobAI desktop app is running
• Check that API is available at http://127.0.0.1:8686

"Bridge not running" error

• Use start_bridge tool first before automation
• iOS bridge may take up to 60 seconds to start

Screenshots not visible

• Screenshots are saved to /tmp/mobai/screenshots/
• Use your AI tool's file reading capability to view them

Development

# Clone the repository
git clone https://github.com/MobAI-App/mobai-mcp.git
cd mobai-mcp

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/index.js

License

Apache 2.0 - see LICENSE for details.