launch_app_sim
Launch iOS apps in simulators by providing simulator UUID and bundle identifier for testing and development workflows.
Instructions
Launches an app in an iOS simulator. IMPORTANT: You MUST provide both the simulatorUuid and bundleId parameters.
Note: You must install the app in the simulator before launching. The typical workflow is: build → install → launch. Example: launch_app_sim({ simulatorUuid: 'YOUR_UUID_HERE', bundleId: 'com.example.MyApp' })
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| simulatorUuid | Yes | UUID of the simulator to use (obtained from list_simulators) | |
| bundleId | Yes | Bundle identifier of the app to launch (e.g., 'com.example.MyApp') | |
| args | No | Additional arguments to pass to the app |
Implementation Reference
- src/tools/simulator.ts:279-383 (handler)The core handler function for the 'launch_app_sim' tool. It validates inputs, checks if the app is installed using 'xcrun simctl get_app_container', launches the app with 'xcrun simctl launch', handles success/error responses, and suggests next steps for log capturing.
async (params): Promise<ToolResponse> => { const simulatorUuidValidation = validateRequiredParam('simulatorUuid', params.simulatorUuid); if (!simulatorUuidValidation.isValid) { return simulatorUuidValidation.errorResponse!; } const bundleIdValidation = validateRequiredParam('bundleId', params.bundleId); if (!bundleIdValidation.isValid) { return bundleIdValidation.errorResponse!; } log('info', `Starting xcrun simctl launch request for simulator ${params.simulatorUuid}`); // Check if the app is installed in the simulator try { const getAppContainerCmd = [ 'xcrun', 'simctl', 'get_app_container', params.simulatorUuid, params.bundleId, 'app', ]; const getAppContainerResult = await executeCommand( getAppContainerCmd, 'Check App Installed', ); if (!getAppContainerResult.success) { return { content: [ { type: 'text', text: `App is not installed on the simulator. Please use install_app_in_simulator before launching.\n\nWorkflow: build → install → launch.`, }, ], isError: true, }; } } catch { return { content: [ { type: 'text', text: `App is not installed on the simulator (check failed). Please use install_app_in_simulator before launching.\n\nWorkflow: build → install → launch.`, }, ], isError: true, }; } try { const command = ['xcrun', 'simctl', 'launch', params.simulatorUuid, params.bundleId]; if (params.args && params.args.length > 0) { command.push(...params.args); } const result = await executeCommand(command, 'Launch App in Simulator'); if (!result.success) { return { content: [ { type: 'text', text: `Launch app in simulator operation failed: ${result.error}`, }, ], }; } return { content: [ { type: 'text', text: `App launched successfully in simulator ${params.simulatorUuid}`, }, { type: 'text', text: `Next Steps: 1. You can now interact with the app in the simulator. 2. Log capture options: - Option 1: Capture structured logs only (app continues running): start_sim_log_cap({ simulatorUuid: "${params.simulatorUuid}", bundleId: "${params.bundleId}" }) - Option 2: Capture both console and structured logs (app will restart): start_sim_log_cap({ simulatorUuid: "${params.simulatorUuid}", bundleId: "${params.bundleId}", captureConsole: true }) - Option 3: Restart with logs in one step: launch_app_logs_sim({ simulatorUuid: "${params.simulatorUuid}", bundleId: "${params.bundleId}" }) 3. When done with any option, use: stop_sim_log_cap({ logSessionId: 'SESSION_ID' })`, }, ], }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); log('error', `Error during launch app in simulator operation: ${errorMessage}`); return { content: [ { type: 'text', text: `Launch app in simulator operation failed: ${errorMessage}`, }, ], }; } }, - src/tools/simulator.ts:270-278 (schema)Zod schema defining the input parameters for the 'launch_app_sim' tool: required simulatorUuid and bundleId, optional args array.
{ simulatorUuid: z .string() .describe('UUID of the simulator to use (obtained from list_simulators)'), bundleId: z .string() .describe("Bundle identifier of the app to launch (e.g., 'com.example.MyApp')"), args: z.array(z.string()).optional().describe('Additional arguments to pass to the app'), }, - src/tools/simulator.ts:266-385 (registration)The registration function that defines and registers the 'launch_app_sim' tool on the MCP server using server.tool(), including name, description, schema, and handler.
export function registerLaunchAppInSimulatorTool(server: McpServer): void { server.tool( 'launch_app_sim', "Launches an app in an iOS simulator. IMPORTANT: You MUST provide both the simulatorUuid and bundleId parameters.\n\nNote: You must install the app in the simulator before launching. The typical workflow is: build → install → launch. Example: launch_app_sim({ simulatorUuid: 'YOUR_UUID_HERE', bundleId: 'com.example.MyApp' })", { simulatorUuid: z .string() .describe('UUID of the simulator to use (obtained from list_simulators)'), bundleId: z .string() .describe("Bundle identifier of the app to launch (e.g., 'com.example.MyApp')"), args: z.array(z.string()).optional().describe('Additional arguments to pass to the app'), }, async (params): Promise<ToolResponse> => { const simulatorUuidValidation = validateRequiredParam('simulatorUuid', params.simulatorUuid); if (!simulatorUuidValidation.isValid) { return simulatorUuidValidation.errorResponse!; } const bundleIdValidation = validateRequiredParam('bundleId', params.bundleId); if (!bundleIdValidation.isValid) { return bundleIdValidation.errorResponse!; } log('info', `Starting xcrun simctl launch request for simulator ${params.simulatorUuid}`); // Check if the app is installed in the simulator try { const getAppContainerCmd = [ 'xcrun', 'simctl', 'get_app_container', params.simulatorUuid, params.bundleId, 'app', ]; const getAppContainerResult = await executeCommand( getAppContainerCmd, 'Check App Installed', ); if (!getAppContainerResult.success) { return { content: [ { type: 'text', text: `App is not installed on the simulator. Please use install_app_in_simulator before launching.\n\nWorkflow: build → install → launch.`, }, ], isError: true, }; } } catch { return { content: [ { type: 'text', text: `App is not installed on the simulator (check failed). Please use install_app_in_simulator before launching.\n\nWorkflow: build → install → launch.`, }, ], isError: true, }; } try { const command = ['xcrun', 'simctl', 'launch', params.simulatorUuid, params.bundleId]; if (params.args && params.args.length > 0) { command.push(...params.args); } const result = await executeCommand(command, 'Launch App in Simulator'); if (!result.success) { return { content: [ { type: 'text', text: `Launch app in simulator operation failed: ${result.error}`, }, ], }; } return { content: [ { type: 'text', text: `App launched successfully in simulator ${params.simulatorUuid}`, }, { type: 'text', text: `Next Steps: 1. You can now interact with the app in the simulator. 2. Log capture options: - Option 1: Capture structured logs only (app continues running): start_sim_log_cap({ simulatorUuid: "${params.simulatorUuid}", bundleId: "${params.bundleId}" }) - Option 2: Capture both console and structured logs (app will restart): start_sim_log_cap({ simulatorUuid: "${params.simulatorUuid}", bundleId: "${params.bundleId}", captureConsole: true }) - Option 3: Restart with logs in one step: launch_app_logs_sim({ simulatorUuid: "${params.simulatorUuid}", bundleId: "${params.bundleId}" }) 3. When done with any option, use: stop_sim_log_cap({ logSessionId: 'SESSION_ID' })`, }, ], }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); log('error', `Error during launch app in simulator operation: ${errorMessage}`); return { content: [ { type: 'text', text: `Launch app in simulator operation failed: ${errorMessage}`, }, ], }; } }, ); } - src/utils/register-tools.ts:365-369 (registration)Entry in the toolRegistrations array that includes the registerLaunchAppInSimulatorTool function, which is invoked by registerTools() to conditionally register the tool based on environment variables and tool groups.
{ register: registerLaunchAppInSimulatorTool, groups: [ToolGroup.APP_DEPLOYMENT, ToolGroup.IOS_SIMULATOR_WORKFLOW], envVar: 'XCODEBUILDMCP_TOOL_LAUNCH_APP_IN_SIMULATOR', },