@srmorete/mobile-device-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Arellano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+# Mobile Device MCP
+
+An 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.
+
+## How It Works
+
+Three-layer architecture:
+
+1. **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.
+2. **UI tree filter** — Normalizes raw UI trees from both platforms into a unified flat element list.
+3. **MCP server** — The external interface. Handles device discovery, bootstrapping, port allocation, and proxies requests to on-device servers.
+
+Devices 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.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_devices` | List available iOS and Android devices |
+| `screenshot` | Capture the device screen (JPEG) |
+| `uitree` | Get the UI element tree as a flat list, with optional search and limit |
+| `tap` | Tap at screen coordinates |
+| `double_tap` | Double-tap at screen coordinates |
+| `long_press` | Long-press at screen coordinates (configurable duration) |
+| `scroll` | Swipe from start to end coordinates |
+| `type_text` | Type text into the focused element |
+| `press_button` | Press a hardware/navigation button (home, back, enter, volumeUp/Down, dpadUp/Down/Left/Right/Center) |
+| `launch_app` | Launch an app by bundle ID / package name |
+| `terminate_app` | Force-stop an app |
+| `list_apps` | List installed apps |
+| `run_code` | Execute sandboxed JavaScript on-device (see [run_code](#run_code) below) |
+
+### run_code
+
+Agents can pass code _that looks like_ UIAutomator or XCUITest, both being Javascript under the hood.
+The sandbox restricts (Android) potentially dangerous Java operations and only allows (iOS) some XCUITest-ish commands
+
+- **Android:** Rhino engine with UIAutomator bindings — `uiDevice` (click, swipe, find elements, press keys, read display info), `By` (selectors), `Until` (wait conditions), `console.log()`
+- **iOS:** JavaScriptCore with XCUITest bindings — `app` (query elements, tap, type, swipe), `springboard`, `device`, `openApp(bundleId)`, `sleep(ms)`, `console.log()`
+
+Both platforms automatically kill runaway scripts (infinite loops) and create a fresh sandbox per call.
+
+## Prerequisites
+
+- **Node.js** 18+ (for running via `npx`)
+- **Android:** Android SDK with `adb` on PATH
+- **iOS Simulator:** Xcode with `xcrun`, `simctl`
+- **iOS Real Device:** Xcode with `xcodebuild`, `devicectl`, and `iproxy` (from [libimobiledevice](https://libimobiledevice.org/))
+- **Building from source:** [Bun](https://bun.sh/) runtime, Gradle (Android), Xcode (iOS)
+
+## Installation
+
+### Claude Code
+
+```bash
+claude mcp add mobile-device-mcp -- npx -y mobile-device-mcp
+```
+
+Or with custom ports:
+```bash
+claude mcp add mobile-device-mcp -e MDMS_PORT_ANDROID=20000 -e MDMS_PORT_IOS=21000 -- npx -y mobile-device-mcp
+```
+
+### Modifying `.mcp.json` (Cursor, Claude Desktop, etc)
+
+```json
+{
+  "mcpServers": {
+    "mobile-device-mcp": {
+      "command": "npx",
+      "args": ["-y", "mobile-device-mcp"],
+      "env": {
+        "MDMS_PORT_ANDROID": "18000",           # optional
+        "MDMS_PORT_IOS": "19000"                # optional
+      }
+    }
+  }
+}
+```
+
+## Building from Source
+
+```bash
+git clone <repo-url>
+cd mobile-device-mcp
+bun install
+
+# Build drivers for both platforms and pack tarball
+./scripts/build.sh
+```
+
+The 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.
+
+To run locally during development:
+
+```bash
+bun run start           # Start the MCP server
+bun test                # Run the test suite
+```
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---------------------|---------|-------------|
+| `MDMS_PORT_ANDROID` | 18000 | Base port for Android on-device servers |
+| `MDMS_PORT_IOS` | 19000 | Base port for iOS on-device servers |
+
+Ports are assigned sequentially — first Android device gets `18000`, second gets `18001`, and so on. Same for iOS starting at `19000`.
+
+## Acknowledgements
+
+Mobile 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).
+Used as inspiration but reframed the current approach to be multi-device and with seamless Native/WebView support (especially on Android).
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../src/server/index.ts";

package/drivers/ios/Debug-iphonesimulator/FlyingFox.swiftmodule/arm64-apple-ios-simulator.abi.json

@@ -0,0 +1,9 @@
+{
+  "ABIRoot": {
+    "kind": "Root",
+    "name": "NO_MODULE",
+    "printedName": "NO_MODULE",
+    "json_format_version": 8
+  },
+  "ConstValues": []
+}

package/drivers/ios/Debug-iphonesimulator/FlyingFox.swiftmodule/x86_64-apple-ios-simulator.abi.json

@@ -0,0 +1,9 @@
+{
+  "ABIRoot": {
+    "kind": "Root",
+    "name": "NO_MODULE",
+    "printedName": "NO_MODULE",
+    "json_format_version": 8
+  },
+  "ConstValues": []
+}

package/drivers/ios/Debug-iphonesimulator/FlyingSocks.swiftmodule/arm64-apple-ios-simulator.abi.json

@@ -0,0 +1,9 @@
+{
+  "ABIRoot": {
+    "kind": "Root",
+    "name": "NO_MODULE",
+    "printedName": "NO_MODULE",
+    "json_format_version": 8
+  },
+  "ConstValues": []
+}

package/drivers/ios/Debug-iphonesimulator/FlyingSocks.swiftmodule/x86_64-apple-ios-simulator.abi.json

@@ -0,0 +1,9 @@
+{
+  "ABIRoot": {
+    "kind": "Root",
+    "name": "NO_MODULE",
+    "printedName": "NO_MODULE",
+    "json_format_version": 8
+  },
+  "ConstValues": []
+}

package/drivers/ios/Debug-iphonesimulator/UITreeServerApp.app/PkgInfo

@@ -0,0 +1 @@
+APPL????

package/drivers/ios/Debug-iphonesimulator/UITreeServerApp.app/_CodeSignature/CodeResources

@@ -0,0 +1,128 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>files</key>
+	<dict>
+		<key>Info.plist</key>
+		<data>
+		TFvXdn+vquX2XbAcQS9N28ukCbc=
+		</data>
+		<key>PkgInfo</key>
+		<data>
+		n57qDP4tZfLD1rCS43W0B4LQjzE=
+		</data>
+		<key>UITreeServerApp.debug.dylib</key>
+		<data>
+		7/gpDja7DcUoUJ+E9Q9cxaq7PG8=
+		</data>
+		<key>__preview.dylib</key>
+		<data>
+		mlUGw6/92PWjxTZrPclOxbWqLuw=
+		</data>
+	</dict>
+	<key>files2</key>
+	<dict>
+		<key>UITreeServerApp.debug.dylib</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			qBh+yIua0kTl4yy+Ogl0tZgKupqm6WieSDRJIUEdckU=
+			</data>
+		</dict>
+		<key>__preview.dylib</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			vJIufKr3iR4TKISDiyf6NIJRyaZqQQwbzuSYvKhLR/8=
+			</data>
+		</dict>
+	</dict>
+	<key>rules</key>
+	<dict>
+		<key>^.*</key>
+		<true/>
+		<key>^.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^version.plist$</key>
+		<true/>
+	</dict>
+	<key>rules2</key>
+	<dict>
+		<key>.*\.dSYM($|/)</key>
+		<dict>
+			<key>weight</key>
+			<real>11</real>
+		</dict>
+		<key>^(.*/)?\.DS_Store$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>2000</real>
+		</dict>
+		<key>^.*</key>
+		<true/>
+		<key>^.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^Info\.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^PkgInfo$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^embedded\.provisionprofile$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^version\.plist$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+	</dict>
+</dict>
+</plist>

package/drivers/ios/Debug-iphonesimulator/UITreeServerApp.swiftmodule/arm64-apple-ios-simulator.abi.json

@@ -0,0 +1,9 @@
+{
+  "ABIRoot": {
+    "kind": "Root",
+    "name": "NO_MODULE",
+    "printedName": "NO_MODULE",
+    "json_format_version": 8
+  },
+  "ConstValues": []
+}

package/drivers/ios/Debug-iphonesimulator/UITreeServerApp.swiftmodule/x86_64-apple-ios-simulator.abi.json

@@ -0,0 +1,9 @@
+{
+  "ABIRoot": {
+    "kind": "Root",
+    "name": "NO_MODULE",
+    "printedName": "NO_MODULE",
+    "json_format_version": 8
+  },
+  "ConstValues": []
+}

package/drivers/ios/Debug-iphonesimulator/UITreeServerUITests-Runner.app/Frameworks/Testing.framework/_CodeSignature/CodeResources

@@ -0,0 +1,168 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>files</key>
+	<dict>
+		<key>Info.plist</key>
+		<data>
+		hmbdRA8IdDack51L+UOF8iuK1Ec=
+		</data>
+		<key>Modules/Testing.swiftcrossimport/Foundation.swiftoverlay</key>
+		<data>
+		YTs8xm0XTk+De36jTobLiYDGRzE=
+		</data>
+		<key>Modules/Testing.swiftmodule/arm64-apple-ios-simulator.swiftdoc</key>
+		<data>
+		fXctRQEv5AEJ6fM8vApK+SEhdgg=
+		</data>
+		<key>Modules/Testing.swiftmodule/arm64-apple-ios-simulator.swiftinterface</key>
+		<data>
+		Kab4tEUQmQYq/a2P5XrKxMCGFZg=
+		</data>
+		<key>Modules/Testing.swiftmodule/x86_64-apple-ios-simulator.swiftdoc</key>
+		<data>
+		+u9VRM6oIDKvBzT5w91Ib7xjHYU=
+		</data>
+		<key>Modules/Testing.swiftmodule/x86_64-apple-ios-simulator.swiftinterface</key>
+		<data>
+		FJeCed5EZF4WgJYi1yPWLiUhu1I=
+		</data>
+		<key>version.plist</key>
+		<data>
+		p+J2GYH/P3JsPjNTM/YjxcqNQ7k=
+		</data>
+	</dict>
+	<key>files2</key>
+	<dict>
+		<key>Modules/Testing.swiftcrossimport/Foundation.swiftoverlay</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			zXQFaqVc3q2xEVpQ0j8FbSpWomb4cEKThbS+u0bNRqA=
+			</data>
+		</dict>
+		<key>Modules/Testing.swiftmodule/arm64-apple-ios-simulator.swiftdoc</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			FXfoaoVTNTpF+C2Wyq+2xh5lAw1xfJs+XwpwOBzOInQ=
+			</data>
+		</dict>
+		<key>Modules/Testing.swiftmodule/arm64-apple-ios-simulator.swiftinterface</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			FUr57ta6dvdHdlKvA4mWjPPzd/2MVmYRrLE/V818vVo=
+			</data>
+		</dict>
+		<key>Modules/Testing.swiftmodule/x86_64-apple-ios-simulator.swiftdoc</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			zvkTxZeehkxFrRFFmebQ2zEXBtUkxbPaqwyhfS//dAA=
+			</data>
+		</dict>
+		<key>Modules/Testing.swiftmodule/x86_64-apple-ios-simulator.swiftinterface</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			fMGetEgOdOGMnhTtgnF+Bj/o4rQrU0IHXqX4VoDIQsQ=
+			</data>
+		</dict>
+		<key>version.plist</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			wl+jhzNbr/BLCMWhbmRzJqDSgfXR+w2RKRmZ/2NSZnw=
+			</data>
+		</dict>
+	</dict>
+	<key>rules</key>
+	<dict>
+		<key>^.*</key>
+		<true/>
+		<key>^.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^version.plist$</key>
+		<true/>
+	</dict>
+	<key>rules2</key>
+	<dict>
+		<key>.*\.dSYM($|/)</key>
+		<dict>
+			<key>weight</key>
+			<real>11</real>
+		</dict>
+		<key>^(.*/)?\.DS_Store$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>2000</real>
+		</dict>
+		<key>^.*</key>
+		<true/>
+		<key>^.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^Info\.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^PkgInfo$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^embedded\.provisionprofile$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^version\.plist$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+	</dict>
+</dict>
+</plist>

package/drivers/ios/Debug-iphonesimulator/UITreeServerUITests-Runner.app/Frameworks/Testing.framework/version.plist

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>BuildAliasOf</key>
+	<string>Citrine</string>
+	<key>BuildVersion</key>
+	<string>24</string>
+	<key>CFBundleShortVersionString</key>
+	<string>1.0</string>
+	<key>CFBundleVersion</key>
+	<string>1501</string>
+	<key>ProjectName</key>
+	<string>Citrine_iOS_Sim</string>
+	<key>SourceVersion</key>
+	<string>1501000000000000</string>
+</dict>
+</plist>