{
  "markdown": "# MobAI MCP Server\n\n[![npm version](https://img.shields.io/npm/v/mobai-mcp.svg)](https://www.npmjs.com/package/mobai-mcp)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/license/Apache-2.0)\n\nMCP (Model Context Protocol) server for [MobAI](https://mobai.run) — 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.\n\n## How it works\n\nAll 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.\n\nA small set of companion tools handles device discovery, screenshots, app management, and running `.mob` test files.\n\n## Prerequisites\n\n- Node.js 18+\n- [MobAI desktop app](https://mobai.run) running locally (HTTP API on `127.0.0.1:8686`)\n- A connected Android or iOS device, emulator, or simulator\n\n## Installation\n\n### Claude Code\n\n```bash\nclaude mcp add mobai -- npx -y mobai-mcp\n```\n\n### Cursor\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"mobai\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mobai-mcp\"]\n    }\n  }\n}\n```\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"mobai\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mobai-mcp\"]\n    }\n  }\n}\n```\n\n### Windsurf / Cline / other MCP clients\n\nThe server speaks stdio — use your client's generic MCP configuration:\n\n```json\n{\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"mobai-mcp\"]\n}\n```\n\n## Tools\n\n### Device management\n\n| Tool | Description |\n|---|---|\n| `list_devices` | List all connected Android and iOS devices |\n| `get_device` | Get details about a specific device |\n| `start_bridge` | Start the automation bridge on a device (required before interaction) |\n| `stop_bridge` | Stop the automation bridge |\n| `claim_device` | Claim exclusive use of a device for this session (usually optional: acting on an unclaimed device auto-claims it) |\n| `release_device` | Release one or all device leases held by this session |\n\n### Screenshots\n\n| Tool | Description |\n|---|---|\n| `get_screenshot` | Fast, low-quality screenshot for LLM visual analysis (may be downscaled; response includes scale factor) |\n| `save_screenshot` | Full-quality PNG to disk for reporting, debugging, or sharing |\n\n### Apps\n\n| Tool | Description |\n|---|---|\n| `list_apps` | List installed apps on the device |\n| `install_app` | Install an `.apk` or `.ipa` from a local file path |\n| `uninstall_app` | Uninstall an app by bundle ID / package name |\n| `debug_app` | Launch an app in debug mode and write stdout/stderr to a log file |\n\n### Automation\n\n| Tool | Description |\n|---|---|\n| `execute_dsl` | **Primary tool.** Execute a batch of DSL steps: tap, type, swipe, observe, assertions, web automation, metrics, screen recording, and more. |\n\n### Test management\n\nTests 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.\n\n| Tool | Description |\n|---|---|\n| `test_get_active` | Get the active test project directory and its `.mob` cases |\n| `test_list_projects` | List all known test project directories with their `.mob` cases |\n| `test_run` | Run a `.mob` test case on a device (`project_dir` + `case_path` + `device_id`, optional `params` for `${name}` substitution) |\n\n## Resources\n\nRead these **before** attempting any device interaction — they describe the DSL schema, action set, predicates, failure strategies, and `.mob` syntax.\n\n| URI | Purpose |\n|---|---|\n| `mobai://reference/device-automation` | How to control devices — guide, all DSL actions, predicates, and failure strategies |\n| `mobai://reference/testing` | Testing workflow, rules, error fixes, and `.mob` script syntax |\n\n## Example\n\nOpen the iOS Settings app, navigate to Wi-Fi, and verify the toggle exists:\n\n```json\n{\n  \"version\": \"0.2\",\n  \"steps\": [\n    {\"action\": \"open_app\", \"bundle_id\": \"com.apple.Preferences\"},\n    {\"action\": \"wait_for\", \"predicate\": {\"text\": \"Settings\"}, \"timeout_ms\": 3000},\n    {\"action\": \"tap\", \"predicate\": {\"text_contains\": \"Wi-Fi\"}},\n    {\"action\": \"wait_for\", \"predicate\": {\"type\": \"switch\"}, \"timeout_ms\": 3000},\n    {\"action\": \"assert_exists\", \"predicate\": {\"type\": \"switch\"}},\n    {\"action\": \"observe\", \"include\": [\"ui_tree\"]}\n  ]\n}\n```\n\nPass this as the `commands` argument (a JSON string) to `execute_dsl` along with a `device_id` from `list_devices`.\n\n## Troubleshooting\n\n**\"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](https://mobai.run/download).\n\n**\"Bridge not running\"** — Call `start_bridge` first. The iOS bridge can take up to a minute to come up.\n\n**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.\n\n## Development\n\n```bash\ngit clone https://github.com/MobAI-App/mobai-mcp.git\ncd mobai-mcp\nnpm install\nnpm run build\nnode dist/index.js\n```\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE).\n",
  "bytes": 5766,
  "sha": "19a979ca5339983cfef76e59751ffae767283352112861996b1f1ca5acccdf69",
  "repo_slug": "mobai-app/mobai-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mobai_app_mobai_mcp_fcc3094a/readme"
}