Mobai MCP

🚀 MobAI MCP Server

The MCP (Model Context Protocol) server for MobAI, enabling AI - powered mobile device automation. It allows AI coding assistants such as 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.

📦 Installation

Prerequisites

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

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

💻 Usage Examples

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"

📚 Documentation

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 (supports text_regex and bounds filtering)
• 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

🔧 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.