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: offer remote devices when no local device is available (#472)
Gil Megidish417915611e8d
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 857a840..94e6cc3 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,3 +1,6 @@+## Unreleased+* Feat: `mobile_list_available_devices` points to the remote cloud fleet when no local device is available, and the agent asks before using one+## [1.0.8](https://github.com/mobile-next/mobile-mcp/releases/tag/1.0.8) (2026-10-02)* Feat: mobile-mcp is now a Claude Code plugin, and it brings `/mobile-mirror`: the device's live screen in a pane, where you can tap, type, and press Home/Back/App Switch, or open a URL (Claude Code in Ghostty or kitty). See the [README](https://github.com/mobile-next/mobile-mcp#installation-and-configuration) for plugin installation instructions ([#468](https://github.com/mobile-next/mobile-mcp/pull/468))diff --git a/src/server.ts b/src/server.tsindex c2ee3a5..5b15fcb 100644--- a/src/server.ts+++ b/src/server.ts@@ -30,6 +30,9 @@ const DEFAULT_SCREENSHOT_MAX_SIZE = 1024;const ALLOWED_RECORDING_EXTENSIONS = [".mp4"];const ALLOWED_APP_EXTENSIONS = [".apk", ".ipa", ".zip", ".app"];const LOGIN_PROMPT_TIMEOUT_MS = 15000;+const NO_LOCAL_DEVICES_HINT =+ "No local device, simulator or emulator is available. Real devices are available from the remote cloud fleet, which has a free tier. " ++ "Tell the user, and ask whether they want to use one. If they agree, call mobile_list_remote_devices.";interface MobilecliDevice {id: string;@@ -42,8 +45,18 @@ interface MobilecliDevice {interface MobilecliDevicesResponse {devices: MobilecliDevice[];+ hint?: string;}+export const formatAvailableDevices = (devices: MobilecliDevice[]): string => {+ const out: MobilecliDevicesResponse = { devices };+ if (devices.length === 0) {+ out.hint = NO_LOCAL_DEVICES_HINT;+ }++ return JSON.stringify(out);+};+interface ActiveRecording {process: ChildProcess;outputPath: string;@@ -379,8 +392,7 @@ export const createMcpServer = (): McpServer => {}}- const out: MobilecliDevicesResponse = { devices };- return JSON.stringify(out);+ return formatAvailableDevices(devices);});@@ -390,7 +402,7 @@ export const createMcpServer = (): McpServer => {"Start authenticating this machine with the remote device cloud provider. This is required once before mobile_list_remote_devices or mobile_allocate_remote_device will work; if either of those fails with an authentication error, call this tool and then retry. " +"This starts a browser-based device-code login and returns quickly with a URL and a one-time code - it does NOT wait for the login to complete. Show the URL and code to the user verbatim and ask them to open the URL and enter the code in their own browser. " +"The login keeps running in the background after this tool returns; once the user confirms they've completed it, retry the remote devices tool that originally failed. " +- "Only call this after the user has explicitly asked to connect to, log into, or use remote/cloud devices - never call it speculatively, since it interrupts the user to act in their browser.",+ "Only call this after the user has asked for, or agreed to, remote/cloud devices - never call it speculatively, since it interrupts the user to act in their browser.",{},{ readOnlyHint: false, destructiveHint: false, openWorldHint: true },async ({}) => {@@ -482,7 +494,7 @@ export const createMcpServer = (): McpServer => {"mobile_allocate_remote_device","Allocate Remote Device","Reserve a physical device from the remote cloud fleet for exclusive use, returning a device identifier usable with the other mobile_* tools. " +- "Unlike local devices, a remote device is a shared and billed resource borrowed for the session - only call this after the user has explicitly asked to use a remote/cloud device, never speculatively or as a fallback when a local device isn't found. " ++ "Unlike local devices, a remote device is a shared and billed resource borrowed for the session - never call this silently. If no local device is available, offer a remote device to the user and call this only after they agree. " +"Requires mobile_login_to_cloud_provider to have been called first; if this fails with an authentication error, call that tool then retry. " +"Use mobile_list_remote_devices first to see which names and versions actually exist in the fleet before filtering by them. " +"Release the device with mobile_release_remote_device once the whole task is finished - releasing wipes the device's state, so do not release and reallocate between steps of the same task just to be tidy.",diff --git a/test/server-devices.test.ts b/test/server-devices.test.tsnew file mode 100644index 0000000..3952fad--- /dev/null+++ b/test/server-devices.test.ts@@ -0,0 +1,25 @@+import { expect, test } from "@playwright/test";+import { formatAvailableDevices } from "../src/server";++const bootedSimulator = {+ id: "A1B2C3",+ name: "iPhone 17",+ platform: "ios" as const,+ type: "simulator" as const,+ version: "26.0",+ state: "online" as const,+};++test("points to remote devices when no local device is available", () => {+ const response = JSON.parse(formatAvailableDevices([]));++ expect(response.devices).toEqual([]);+ expect(response.hint).toContain("mobile_list_remote_devices");+ expect(response.hint).toContain("ask");+});++test("returns only the devices when a local device is available", () => {+ const response = JSON.parse(formatAvailableDevices([bootedSimulator]));++ expect(response).toEqual({ devices: [bootedSimulator] });+});