{"id":49206352,"url":"https://github.com/srmorete/mobile-device-mcp","last_synced_at":"2026-04-26T04:03:32.700Z","repository":{"id":349314574,"uuid":"1201853890","full_name":"srmorete/mobile-device-mcp","owner":"srmorete","description":"An MCP server to use with iOS and Android. Seamlessly maps Native screens and WebViews. Multiple parallel devices supported.","archived":false,"fork":false,"pushed_at":"2026-04-17T13:07:28.000Z","size":370,"stargazers_count":8,"open_issues_count":4,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-23T18:37:22.753Z","etag":null,"topics":["ai","ai-agents","android","automation","ios","mcp","qa","qa-agent","ui-testing"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@srmorete/mobile-device-mcp","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/srmorete.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-05T08:56:37.000Z","updated_at":"2026-04-20T11:10:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/srmorete/mobile-device-mcp","commit_stats":null,"previous_names":["srmorete/mobile-device-mcp"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/srmorete/mobile-device-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srmorete%2Fmobile-device-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srmorete%2Fmobile-device-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srmorete%2Fmobile-device-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srmorete%2Fmobile-device-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/srmorete","download_url":"https://codeload.github.com/srmorete/mobile-device-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srmorete%2Fmobile-device-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32285283,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"online","status_checked_at":"2026-04-26T02:00:05.962Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","android","automation","ios","mcp","qa","qa-agent","ui-testing"],"created_at":"2026-04-23T18:04:25.540Z","updated_at":"2026-04-26T04:03:32.671Z","avatar_url":"https://github.com/srmorete.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mobile Device MCP\n\nAn MCP server that lets AI agents control iOS and Android devices (tap, scroll, type, take screenshots, read UI trees, and run code). Works with multiple devices at the same time.\n\n## How It Works\n\nThree-layer architecture:\n\n1. **On-device servers** — Lightweight HTTP servers running on each mobile device (UIAutomator on Android, XCUITest on iOS) that expose the accessibility tree and accept interaction commands.\n2. **UI tree filter** — Normalizes raw UI trees from both platforms into a unified flat element list.\n3. **MCP server** — The external interface. Handles device discovery, bootstrapping, port allocation, and proxies requests to on-device servers.\n\nDevices are bootstrapped on first use — the server installs the driver app, allocates a port, starts the on-device server, and polls until it's healthy. After that, all tool calls are proxied over localhost HTTP with per-device bearer token auth.\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `list_devices` | List available iOS and Android devices |\n| `screenshot` | Capture the device screen (JPEG) |\n| `uitree` | Get the UI element tree as a flat list, with optional search and limit |\n| `tap` | Tap at screen coordinates |\n| `double_tap` | Double-tap at screen coordinates |\n| `long_press` | Long-press at screen coordinates (configurable duration) |\n| `scroll` | Swipe from start to end coordinates |\n| `type_text` | Type text into the focused element |\n| `press_button` | Press a hardware/navigation button (home, back, enter, volumeUp/Down, dpadUp/Down/Left/Right/Center) |\n| `launch_app` | Launch an app by bundle ID / package name |\n| `terminate_app` | Force-stop an app |\n| `list_apps` | List installed apps |\n| `run_code` | Execute sandboxed JavaScript on-device (see [run_code](#run_code) below) |\n\n### run_code\n\nAgents can pass code _that looks like_ UIAutomator or XCUITest, both being Javascript under the hood.\nThe sandbox restricts (Android) potentially dangerous Java operations and only allows (iOS) some XCUITest-ish commands\n\n- **Android:** Rhino engine with UIAutomator bindings — `uiDevice` (click, swipe, find elements, press keys, read display info), `By` (selectors), `Until` (wait conditions), `console.log()`\n- **iOS:** JavaScriptCore with XCUITest bindings — `app` (query elements, tap, type, swipe), `springboard`, `device`, `openApp(bundleId)`, `sleep(ms)`, `console.log()`\n\nBoth platforms automatically kill runaway scripts (infinite loops) and create a fresh sandbox per call.\n\n## Prerequisites\n\n- **Node.js** 18+ (for running via `npx`)\n- **Android:** Android SDK with `adb` on PATH\n- **iOS Simulator:** Xcode with `xcrun`, `simctl`\n- **iOS Real Device:** Xcode with `xcodebuild`, `devicectl`, and `iproxy` (from [libimobiledevice](https://libimobiledevice.org/))\n- **Building from source:** [Bun](https://bun.sh/) runtime, Gradle (Android), Xcode (iOS)\n\n## Installation\n\n### Claude Code\n\n```bash\nclaude mcp add mobile-device-mcp -- npx -y @srmorete/mobile-device-mcp@latest\n```\n\nOr with custom ports:\n```bash\nclaude mcp add mobile-device-mcp -e MDMS_PORT_ANDROID=20000 -e MDMS_PORT_IOS=21000 -- npx -y @srmorete/mobile-device-mcp@latest\n```\n\n### Modifying `.mcp.json` (Cursor, Claude Desktop, etc)\n\n```json\n{\n  \"mcpServers\": {\n    \"mobile-device-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@srmorete/mobile-device-mcp@latest\"],\n      \"env\": {\n        \"MDMS_PORT_ANDROID\": \"18000\",           # optional\n        \"MDMS_PORT_IOS\": \"19000\"                # optional\n      }\n    }\n  }\n}\n```\n\n## Building from Source\n\n```bash\ngit clone \u003crepo-url\u003e\ncd mobile-device-mcp\nbun install\n\n# Build drivers for both platforms and pack tarball\n./scripts/build.sh\n```\n\nThe build script compiles the on-device drivers (Android APKs via Gradle, iOS test bundle via xcodebuild), copies them to `drivers/`, and creates an npm tarball.\n\nTo run locally during development:\n\n```bash\nbun run start           # Start the MCP server\nbun test                # Run the test suite\n```\n\n## Configuration\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `MDMS_PORT_ANDROID` | 18000 | Base port for Android on-device servers |\n| `MDMS_PORT_IOS` | 19000 | Base port for iOS on-device servers |\n\nPorts are assigned sequentially — first Android device gets `18000`, second gets `18001`, and so on. Same for iOS starting at `19000`.\n\n## Acknowledgements\n\nMobile Device MCP server stands on the shoulders of giants such as [mobile-mcp](https://github.com/mobile-next/mobile-mcp) and [Maestro](https://github.com/mobile-dev-inc/maestro).\nUsed as inspiration but reframed the current approach to be multi-device and with seamless Native/WebView support (especially on Android).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrmorete%2Fmobile-device-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsrmorete%2Fmobile-device-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrmorete%2Fmobile-device-mcp/lists"}