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.
TypeScript agentandroidandroid-automationappium-alternativeclaude-codecodexcursoremulatoriosios-automationmcpmcp-servermobilemobile-automationmobile-testingreal-devicesimulatorskills
feat: route devices through mobilecli by default (#396)
Gil Megidish349c3c1e8d47
diff --git a/.github/workflows/build.yml b/.github/workflows/build.ymlindex 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.jsonmcp-publisher publishmcp-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.jsdiff --git a/README.md b/README.mdindex 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 Devicesdiff --git a/src/server.ts b/src/server.tsindex 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 workingensureMobilecliAvailable();- // 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 workingensureMobilecliAvailable();- 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.jsnew file mode 100644index 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");