Skip to content

Mobile MCP: let AI agents drive your iOS and Android apps. MCP server for simulators, emulators and real devices. Works with Claude Code, Codex, Cursor and any MCP client.

feat: route devices through mobilecli by default (#396)

Gil Megidish349c3c1e8d47
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index f19b669..64c356f 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -67,3 +67,34 @@ jobs:
sed -i "s/{{VERSION}}/$VERSION/g" server.json
mcp-publisher publish
mcp-publisher logout
+
+ e2e_test:
+ runs-on: self-hosted
+ needs: build
+ timeout-minutes: 15
+
+ steps:
+ - uses: actions/checkout@v5
+ with:
+ persist-credentials: false
+
+ - name: Install dependencies
+ run: npm ci --ignore-scripts
+
+ - name: Build
+ run: npm run build
+
+ - name: Configure mobile-mcp MCP server
+ run: |
+ claude mcp remove mobile-mcp --scope local || true
+ claude mcp add mobile-mcp --scope local -- node "$(pwd)/lib/index.js"
+
+ - name: Run Android emulator test prompt
+ run: |
+ set -o pipefail
+ claude --dangerously-skip-permissions -p < test/prompt-android-emulator.md | node test/validate-response.js
+
+ - name: Run iOS simulator test prompt
+ run: |
+ set -o pipefail
+ claude --dangerously-skip-permissions -p < test/prompt-ios-simulator.md | node test/validate-response.js
diff --git a/README.md b/README.md
index 97cc6f7..a0d9976 100644
--- a/README.md
+++ b/README.md
@@ -467,6 +467,7 @@ Gmail to contacts "[email protected]".
| `MOBILEMCP_AUTH` | Require a Bearer token on the SSE server — every request must then send `Authorization: Bearer <token>`. | `MOBILEMCP_AUTH=my-secret-token` |
| `MOBILEMCP_DISABLE_TELEMETRY` | Disable anonymous usage telemetry. | `MOBILEMCP_DISABLE_TELEMETRY=1` |
| `MOBILEMCP_ALLOW_UNSAFE_URLS` | Allow `mobile_open_url` to open non-standard URL schemes (blocked by default). | `MOBILEMCP_ALLOW_UNSAFE_URLS=1` |
+| `MOBILEMCP_LEGACY_ROBOT` | Use the legacy platform-specific robots for Android devices and physical iOS devices. iOS simulators continue to use `mobilecli`. | `MOBILEMCP_LEGACY_ROBOT=1` |
### Simulators, Emulators, and Real Devices
diff --git a/src/server.ts b/src/server.ts
index 178de1e..4c03a2c 100644
--- a/src/server.ts
+++ b/src/server.ts
@@ -120,6 +120,7 @@ export const createMcpServer = (): McpServer => {
Version: getAgentVersion(),
NodeVersion: process.version,
CI: process.env.CI || "0",
+ RobotMode: process.env.MOBILEMCP_LEGACY_ROBOT === "1" ? "legacy" : "mobilecli",
};
const clientName = getClientName();
@@ -168,35 +169,39 @@ export const createMcpServer = (): McpServer => {
// from now on, we must have mobilecli working
ensureMobilecliAvailable();
- // Check if it's an iOS device
- const iosManager = new IosManager();
- const iosDevices = iosManager.listDevices();
- const iosDevice = iosDevices.find(d => d.deviceId === deviceId);
- if (iosDevice) {
- posthog("get_robot", { "DevicePlatform": "ios", "DeviceType": "real" }).then();
- return new IosRobot(deviceId);
- }
+ const legacyRobot = process.env.MOBILEMCP_LEGACY_ROBOT === "1";
+ if (legacyRobot) {
+ // Check if it's an iOS device
+ const iosManager = new IosManager();
+ const iosDevices = iosManager.listDevices();
+ const iosDevice = iosDevices.find(d => d.deviceId === deviceId);
+ if (iosDevice) {
+ posthog("get_robot", { "DevicePlatform": "ios", "DeviceType": "real" }).then();
+ return new IosRobot(deviceId);
+ }
- // Check if it's an Android device
- const androidManager = new AndroidDeviceManager();
- const androidDevices = androidManager.getConnectedDevices();
- const androidDevice = androidDevices.find(d => d.deviceId === deviceId);
- if (androidDevice) {
- posthog("get_robot", { "DevicePlatform": "android" }).then();
- return new AndroidRobot(deviceId);
+ // Check if it's an Android device
+ const androidManager = new AndroidDeviceManager();
+ const androidDevices = androidManager.getConnectedDevices();
+ const androidDevice = androidDevices.find(d => d.deviceId === deviceId);
+ if (androidDevice) {
+ posthog("get_robot", { "DevicePlatform": "android", "DeviceType": androidDevice.deviceType }).then();
+ return new AndroidRobot(deviceId);
+ }
}
- // Check if it's a simulator (will later replace all other device types as well)
- const response = mobilecli.getDevices({
+ const response = mobilecli.getDevices(legacyRobot ? {
platform: "ios",
type: "simulator",
includeOffline: false,
+ } : {
+ includeOffline: false,
});
if (response.status === "ok" && response.data && response.data.devices) {
for (const device of response.data.devices) {
if (device.id === deviceId) {
- if (!agentVerifiedSimulators.has(deviceId)) {
+ if (device.platform === "ios" && device.type === "simulator" && !agentVerifiedSimulators.has(deviceId)) {
const agentStatus = mobilecli.agentStatus(deviceId);
if (agentStatus.status === "fail") {
mobilecli.agentInstall(deviceId);
@@ -205,7 +210,7 @@ export const createMcpServer = (): McpServer => {
agentVerifiedSimulators.add(deviceId);
}
- posthog("get_robot", { "DevicePlatform": "ios", "DeviceType": "simulator" }).then();
+ posthog("get_robot", { "DevicePlatform": device.platform, "DeviceType": device.type }).then();
return new MobileDevice(deviceId);
}
}
@@ -225,66 +230,75 @@ export const createMcpServer = (): McpServer => {
// from today onward, we must have mobilecli working
ensureMobilecliAvailable();
- const iosManager = new IosManager();
- const androidManager = new AndroidDeviceManager();
const devices: MobilecliDevice[] = [];
+ const legacyRobot = process.env.MOBILEMCP_LEGACY_ROBOT === "1";
- // Get Android devices with details
- const androidDevices = androidManager.getConnectedDevicesWithDetails();
- telemetry.AndroidCount = androidDevices.length;
- for (const device of androidDevices) {
- devices.push({
- id: device.deviceId,
- name: device.name,
- platform: "android",
- type: "emulator",
- version: device.version,
- state: "online",
- });
- }
+ if (legacyRobot) {
+ const iosManager = new IosManager();
+ const androidManager = new AndroidDeviceManager();
- // Get iOS physical devices with details
- telemetry.IosRealCount = 0;
- try {
- const iosDevices = iosManager.listDevicesWithDetails();
- telemetry.IosRealCount = iosDevices.length;
- for (const device of iosDevices) {
+ // Get Android devices with details
+ const androidDevices = androidManager.getConnectedDevicesWithDetails();
+ telemetry.AndroidCount = androidDevices.length;
+ for (const device of androidDevices) {
devices.push({
id: device.deviceId,
- name: device.deviceName,
- platform: "ios",
- type: "real",
+ name: device.name,
+ platform: "android",
+ type: "emulator",
version: device.version,
state: "online",
});
}
- } catch (error: any) {
- // If go-ios is not available, silently skip
- }
- // Get iOS simulators from mobilecli, including offline ones so we can
- // report how many are installed vs booted. only booted ones are returned.
- const response = mobilecli.getDevices({
- platform: "ios",
- type: "simulator",
- includeOffline: true,
- });
- telemetry.IosSimInstalledCount = 0;
- telemetry.IosSimCount = 0;
- if (response.status === "ok" && response.data && response.data.devices) {
- const simulators = response.data.devices;
- const booted = simulators.filter(device => device.state === "online");
- telemetry.IosSimInstalledCount = simulators.length;
- telemetry.IosSimCount = booted.length;
- for (const device of booted) {
- devices.push({
- id: device.id,
- name: device.name,
- platform: device.platform,
- type: device.type,
- version: device.version,
- state: "online",
- });
+ // Get iOS physical devices with details
+ telemetry.IosRealCount = 0;
+ try {
+ const iosDevices = iosManager.listDevicesWithDetails();
+ telemetry.IosRealCount = iosDevices.length;
+ for (const device of iosDevices) {
+ devices.push({
+ id: device.deviceId,
+ name: device.deviceName,
+ platform: "ios",
+ type: "real",
+ version: device.version,
+ state: "online",
+ });
+ }
+ } catch (error: any) {
+ // If go-ios is not available, silently skip
+ }
+
+ // Get iOS simulators from mobilecli, including offline ones so we can
+ // report how many are installed vs booted. only booted ones are returned.
+ const response = mobilecli.getDevices({
+ platform: "ios",
+ type: "simulator",
+ includeOffline: true,
+ });
+ telemetry.IosSimInstalledCount = 0;
+ telemetry.IosSimCount = 0;
+ if (response.status === "ok" && response.data && response.data.devices) {
+ const simulators = response.data.devices;
+ const booted = simulators.filter(device => device.state === "online");
+ telemetry.IosSimInstalledCount = simulators.length;
+ telemetry.IosSimCount = booted.length;
+ devices.push(...booted);
+ }
+ } else {
+ const response = mobilecli.getDevices({ includeOffline: true });
+ telemetry.AndroidCount = 0;
+ telemetry.IosRealCount = 0;
+ telemetry.IosSimInstalledCount = 0;
+ telemetry.IosSimCount = 0;
+ if (response.status === "ok" && response.data && response.data.devices) {
+ const availableDevices = response.data.devices.filter(device => device.state === "online");
+ telemetry.AndroidCount = availableDevices.filter(device => device.platform === "android").length;
+ telemetry.IosRealCount = availableDevices.filter(device => device.platform === "ios" && device.type === "real").length;
+ telemetry.IosSimInstalledCount = response.data.devices.filter(device => device.platform === "ios" && device.type === "simulator").length;
+ telemetry.IosSimCount = availableDevices.filter(device => device.platform === "ios" && device.type === "simulator").length;
+ devices.push(...availableDevices);
}
}
diff --git a/test/prompt-android-emulator.md b/test/prompt-android-emulator.md
new file mode 100644
index 0000000..4f421bd
--- /dev/null
+++ b/test/prompt-android-emulator.md
@@ -0,0 +1,33 @@
+You are running an acceptance test for mobilecli. The output of this prompt must be a json with a simple "pass" boolean. If the test has failed please
+also include a "error" field in the json to also explain for a human what is the problem. Lastly, include "steps" which is an array of human readable
+steps you took to achieve this task. In "steps" also mention which mcp tools you used.
+
+Your entire final response must be ONLY that JSON object, and nothing else: no summary sentence before it, no commentary after it, no markdown code
+fence around it. The very first character of your response must be "{" and the very last character must be "}".
+
+<test>
+Assert that there is only one Android emulator connected.
+On that Android emulator. List apps and assert "com.mobilenext.Playground" app is installed.
+If it's running then terminate it. Now launch "com.mobilenext.Playground" app.
+Assert that com.mobilenext.Playground app is in the foreground.
+Press HOME button.
+Assert that it's not in the foreground anymore, but instead we're back to app launcher.
+Launch the app again and save a screenshot to "delete-me.png".
+Assert that delete-me.png was created locally on disk, and it's a valid png of at least 512x512 pixels, and 50KB.
+Delete "delete-me.png" file.
+Take a screenshot and assert that there is an image at the top that looks like two phones, one is red and the other is green.
+
+Click on "Basic UI" button. Assert now that there's an element called "Toggle" on screen.
+Press BACK and assert you're in the main menu again. Now click on "Basic UI".
+
+Assert that you see these elements on screen:
+- Text field labelled: "Text Field"
+- Password field labelled: "Password"
+- Multiline text field labelled: "Multiline text"
+
+Click on the first text field, and type "Hello World". List elements on screen and assert you have "Hello World" entered in the text field.
+
+Now swipe up, and make sure you can't see "Text Field" anymore, but instead you see a date selector.
+</test>
+
+
diff --git a/test/prompt-ios-simulator.md b/test/prompt-ios-simulator.md
new file mode 100644
index 0000000..b6432b7
--- /dev/null
+++ b/test/prompt-ios-simulator.md
@@ -0,0 +1,17 @@
+You are running an acceptance test for mobilecli. The output of this prompt must be a json with a simple "pass" boolean. If the test has failed please
+also include a "error" field in the json to also explain for a human what is the problem. Lastly, include "steps" which is an array of human readable
+steps you took to achieve this task. In "steps" also mention which mcp tools you used.
+
+Your entire final response must be ONLY that JSON object, and nothing else: no summary sentence before it, no commentary after it, no markdown code
+fence around it. The very first character of your response must be "{" and the very last character must be "}".
+
+<test>
+Assert that there is only one iOS simulator connected.
+
+Using my iOS simulator. Go to wikipedia and find out what is today's article. Launch the Reminders app. Add a reminder to learn about today's featured
+article.
+
+Next, search for NASA's picture of the day, and take a screenshot to explain to me what's in the photo.
+</test>
+
+
diff --git a/test/validate-response.js b/test/validate-response.js
new file mode 100644
index 0000000..f4dc89e
--- /dev/null
+++ b/test/validate-response.js
@@ -0,0 +1,30 @@
+"use strict";
+
+const fs = require("node:fs");
+
+const raw = fs.readFileSync(0, "utf8").trim();
+
+console.log(raw);
+
+const fenced = raw.match(/^```(?:json)?\s*\n([\s\S]*?)\n```$/);
+const json = fenced ? fenced[1].trim() : raw;
+
+let response;
+try {
+ response = JSON.parse(json);
+} catch (error) {
+ console.error(`Response is not valid JSON: ${error.message}`);
+ process.exit(1);
+}
+
+if (response.pass !== true) {
+ console.error(`Test did not pass: ${response.error || "unknown reason"}`);
+ process.exit(1);
+}
+
+if (!Array.isArray(response.steps)) {
+ console.error("Response is missing a \"steps\" array");
+ process.exit(1);
+}
+
+console.log("Response validated: pass=true, steps is an array");