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: support locales when launching apps (#283)

Gil Megidishcaf6ba3cd586
diff --git a/src/android.ts b/src/android.ts
index 3e01ff0..8378da1 100644
--- a/src/android.ts
+++ b/src/android.ts
@@ -5,7 +5,7 @@ import { existsSync } from "node:fs";
import * as xml from "fast-xml-parser";
import { ActionableError, Button, InstalledApp, Robot, ScreenElement, ScreenElementRect, ScreenSize, SwipeDirection, Orientation } from "./robot";
-import { validatePackageName } from "./utils";
+import { validatePackageName, validateLocale } from "./utils";
export interface AndroidDevice {
deviceId: string;
@@ -140,8 +140,18 @@ export class AndroidRobot implements Robot {
.map(line => line.substring("package:".length));
}
- public async launchApp(packageName: string): Promise<void> {
+ public async launchApp(packageName: string, locale?: string): Promise<void> {
validatePackageName(packageName);
+
+ if (locale) {
+ validateLocale(locale);
+ try {
+ this.silentAdb("shell", "cmd", "locale", "set-app-locales", packageName, "--locales", locale);
+ } catch (error) {
+ // set-app-locales requires Android 13+ (API 33), silently ignore on older versions
+ }
+ }
+
try {
this.silentAdb("shell", "monkey", "-p", packageName, "-c", "android.intent.category.LAUNCHER", "1");
} catch (error) {
diff --git a/src/ios.ts b/src/ios.ts
index 77bb8e0..774464e 100644
--- a/src/ios.ts
+++ b/src/ios.ts
@@ -3,7 +3,7 @@ import { execFileSync } from "node:child_process";
import { WebDriverAgent } from "./webdriver-agent";
import { ActionableError, Button, InstalledApp, Robot, ScreenSize, SwipeDirection, ScreenElement, Orientation } from "./robot";
-import { validatePackageName } from "./utils";
+import { validatePackageName, validateLocale } from "./utils";
const WDA_PORT = 8100;
const IOS_TUNNEL_PORT = 60105;
@@ -138,10 +138,18 @@ export class IosRobot implements Robot {
});
}
- public async launchApp(packageName: string): Promise<void> {
+ public async launchApp(packageName: string, locale?: string): Promise<void> {
validatePackageName(packageName);
await this.assertTunnelRunning();
- await this.ios("launch", packageName);
+ const args = ["launch", packageName];
+ if (locale) {
+ validateLocale(locale);
+ const locales = locale.split(",").map(l => l.trim());
+ args.push("-AppleLanguages", `(${locales.join(", ")})`);
+ args.push("-AppleLocale", locales[0]);
+ }
+
+ await this.ios(...args);
}
public async terminateApp(packageName: string): Promise<void> {
diff --git a/src/iphone-simulator.ts b/src/iphone-simulator.ts
index 901677e..ef95f0e 100644
--- a/src/iphone-simulator.ts
+++ b/src/iphone-simulator.ts
@@ -6,7 +6,7 @@ import { join, basename, extname } from "node:path";
import { trace } from "./logger";
import { WebDriverAgent } from "./webdriver-agent";
import { ActionableError, Button, InstalledApp, Robot, ScreenElement, ScreenSize, SwipeDirection, Orientation } from "./robot";
-import { validatePackageName } from "./utils";
+import { validatePackageName, validateLocale } from "./utils";
export interface Simulator {
name: string;
@@ -102,9 +102,17 @@ export class Simctl implements Robot {
// alternative: this.simctl("openurl", this.simulatorUuid, url);
}
- public async launchApp(packageName: string) {
+ public async launchApp(packageName: string, locale?: string) {
validatePackageName(packageName);
- this.simctl("launch", this.simulatorUuid, packageName);
+ const args = ["launch", this.simulatorUuid, packageName];
+ if (locale) {
+ validateLocale(locale);
+ const locales = locale.split(",").map(l => l.trim());
+ args.push("-AppleLanguages", `(${locales.join(", ")})`);
+ args.push("-AppleLocale", locales[0]);
+ }
+
+ this.simctl(...args);
}
public async terminateApp(packageName: string) {
diff --git a/src/mobile-device.ts b/src/mobile-device.ts
index f1ab039..b0babaa 100644
--- a/src/mobile-device.ts
+++ b/src/mobile-device.ts
@@ -149,8 +149,13 @@ export class MobileDevice implements Robot {
})) as InstalledApp[];
}
- public async launchApp(packageName: string): Promise<void> {
- this.runCommand(["apps", "launch", packageName]);
+ public async launchApp(packageName: string, locale?: string): Promise<void> {
+ const args = ["apps", "launch", packageName];
+ if (locale) {
+ args.push("--locale", locale);
+ }
+
+ this.runCommand(args);
}
public async terminateApp(packageName: string): Promise<void> {
diff --git a/src/robot.ts b/src/robot.ts
index e88821b..59bb344 100644
--- a/src/robot.ts
+++ b/src/robot.ts
@@ -76,7 +76,7 @@ export interface Robot {
/**
* Launch an app.
*/
- launchApp(packageName: string): Promise<void>;
+ launchApp(packageName: string, locale?: string): Promise<void>;
/**
* Terminate an app. If app was already terminated (or non existent) then this
diff --git a/src/server.ts b/src/server.ts
index c8bd321..72e9d52 100644
--- a/src/server.ts
+++ b/src/server.ts
@@ -328,11 +328,12 @@ export const createMcpServer = (): McpServer => {
{
device: z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
packageName: z.string().describe("The package name of the app to launch"),
+ locale: z.string().optional().describe("Comma-separated BCP 47 locale tags to launch the app with (e.g., fr-FR,en-GB)"),
},
{ destructiveHint: true },
- async ({ device, packageName }) => {
+ async ({ device, packageName, locale }) => {
const robot = getRobotFromDevice(device);
- await robot.launchApp(packageName);
+ await robot.launchApp(packageName, locale);
return `Launched app ${packageName}`;
}
);
diff --git a/src/utils.ts b/src/utils.ts
index a93e270..00d8403 100644
--- a/src/utils.ts
+++ b/src/utils.ts
@@ -5,3 +5,9 @@ export function validatePackageName(packageName: string): void {
throw new ActionableError(`Invalid package name: "${packageName}"`);
}
}
+
+export function validateLocale(locale: string): void {
+ if (!/^[a-zA-Z0-9,\- ]+$/.test(locale)) {
+ throw new ActionableError(`Invalid locale: "${locale}"`);
+ }
+}