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: add mobile_get_foreground_app tool (#420)

Gil Megidish794d64dca7f7
diff --git a/README.md b/README.md
index efd3e09..0411b04 100644
--- a/README.md
+++ b/README.md
@@ -75,6 +75,7 @@ How we help to scale mobile automation:
### App Management
- **`mobile_list_apps`** - List all installed apps on the device
+- **`mobile_get_foreground_app`** - Get the app currently in the foreground
- **`mobile_launch_app`** - Launch an app using its package name
- **`mobile_terminate_app`** - Stop and terminate a running app
- **`mobile_install_app`** - Install an app from file (.apk, .ipa, .app, .zip)
diff --git a/src/mobile-device.ts b/src/mobile-device.ts
index 261953a..9fe74cb 100644
--- a/src/mobile-device.ts
+++ b/src/mobile-device.ts
@@ -53,6 +53,14 @@ interface DumpUIResponse {
};
}
+interface ForegroundAppResponse {
+ status: "ok",
+ data: {
+ packageName: string;
+ appName?: string;
+ };
+}
+
interface OrientationResponse {
status: "ok",
data: {
@@ -169,6 +177,14 @@ export class MobileDevice implements Robot {
})) as InstalledApp[];
}
+ public async getForegroundApp(): Promise<InstalledApp> {
+ const response = JSON.parse(this.runCommand(["apps", "foreground"])) as ForegroundAppResponse;
+ return {
+ appName: response.data.appName || response.data.packageName,
+ packageName: response.data.packageName,
+ };
+ }
+
public async launchApp(packageName: string, locale?: string): Promise<void> {
const args = ["apps", "launch", packageName];
if (locale) {
diff --git a/src/robot.ts b/src/robot.ts
index 59bb344..563c8b0 100644
--- a/src/robot.ts
+++ b/src/robot.ts
@@ -73,6 +73,11 @@ export interface Robot {
*/
listApps(): Promise<InstalledApp[]>;
+ /**
+ * Get the app currently in the foreground. Optional, not all robots support it.
+ */
+ getForegroundApp?(): Promise<InstalledApp>;
+
/**
* Launch an app.
*/
diff --git a/src/server.ts b/src/server.ts
index 486e34d..434bf34 100644
--- a/src/server.ts
+++ b/src/server.ts
@@ -458,6 +458,25 @@ export const createMcpServer = (): McpServer => {
}
);
+ tool(
+ "mobile_get_foreground_app",
+ "Get Foreground App",
+ "Get the app currently in the foreground on the device. Use this to verify which app or screen you are on before interacting with it.",
+ {
+ device: z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you.")
+ },
+ { readOnlyHint: true, openWorldHint: false },
+ async ({ device }) => {
+ const robot = getRobotFromDevice(device);
+ if (!robot.getForegroundApp) {
+ throw new ActionableError("Getting the foreground app is not supported in legacy robot mode");
+ }
+
+ const app = await robot.getForegroundApp();
+ return `Foreground app: ${app.appName} (${app.packageName})`;
+ }
+ );
+
tool(
"mobile_launch_app",
"Launch App",
diff --git a/test/mobile-device.test.ts b/test/mobile-device.test.ts
index 9358264..6ad616c 100644
--- a/test/mobile-device.test.ts
+++ b/test/mobile-device.test.ts
@@ -49,4 +49,15 @@ test.describe("MobileDevice", () => {
expect(calls[0]).toEqual(["io", "tap", "450,785", "--device", "test-device"]);
});
});
+
+ test.describe("foreground app", () => {
+
+ test("getForegroundApp should call mobilecli apps foreground and fall back to package name when app name is missing", async () => {
+ const { device, calls } = createMockMobileDevice(JSON.stringify({ status: "ok", data: { packageName: "com.example.app" } }));
+ const app = await device.getForegroundApp();
+
+ expect(calls[0]).toEqual(["apps", "foreground", "--device", "test-device"]);
+ expect(app).toEqual({ appName: "com.example.app", packageName: "com.example.app" });
+ });
+ });
});
diff --git a/test/server-annotations.test.ts b/test/server-annotations.test.ts
index 0c32ea0..5200990 100644
--- a/test/server-annotations.test.ts
+++ b/test/server-annotations.test.ts
@@ -14,6 +14,7 @@ const expectedAnnotations: ToolAnnotationMatrix = {
mobile_allocate_remote_device: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
mobile_release_remote_device: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
mobile_list_apps: { readOnlyHint: true, openWorldHint: false },
+ mobile_get_foreground_app: { readOnlyHint: true, openWorldHint: false },
mobile_launch_app: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
mobile_terminate_app: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
mobile_install_app: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },