list_sims
Retrieve iOS simulator details and UUIDs to identify available testing environments for development workflows.
Instructions
Lists available iOS simulators with their UUIDs.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| enabled | Yes |
Implementation Reference
- src/tools/simulator.ts:102-178 (handler)Handler function that executes 'xcrun simctl list devices available --json', parses and formats available iOS simulators list with UUIDs, states, and suggests next steps.async (): Promise<ToolResponse> => { log('info', 'Starting xcrun simctl list devices request'); try { const command = ['xcrun', 'simctl', 'list', 'devices', 'available', '--json']; const result = await executeCommand(command, 'List Simulators'); if (!result.success) { return { content: [ { type: 'text', text: `Failed to list simulators: ${result.error}`, }, ], }; } try { const simulatorsData = JSON.parse(result.output); let responseText = 'Available iOS Simulators:\n\n'; for (const runtime in simulatorsData.devices) { const devices = simulatorsData.devices[runtime]; if (devices.length === 0) continue; responseText += `${runtime}:\n`; for (const device of devices) { if (device.isAvailable) { responseText += `- ${device.name} (${device.udid})${device.state === 'Booted' ? ' [Booted]' : ''}\n`; } } responseText += '\n'; } responseText += 'Next Steps:\n'; responseText += "1. Boot a simulator: boot_sim({ simulatorUuid: 'UUID_FROM_ABOVE' })\n"; responseText += '2. Open the simulator UI: open_sim({ enabled: true })\n'; responseText += "3. Build for simulator: build_ios_sim_id_proj({ scheme: 'YOUR_SCHEME', simulatorId: 'UUID_FROM_ABOVE' })\n"; // Example using project variant responseText += "4. Get app path: get_sim_app_path_id_proj({ scheme: 'YOUR_SCHEME', platform: 'iOS Simulator', simulatorId: 'UUID_FROM_ABOVE' })"; // Example using project variant return { content: [ { type: 'text', text: responseText, }, ], }; } catch { return { content: [ { type: 'text', text: result.output, }, ], }; } } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); log('error', `Error listing simulators: ${errorMessage}`); return { content: [ { type: 'text', text: `Failed to list simulators: ${errorMessage}`, }, ], }; } },
- src/tools/simulator.ts:99-101 (schema)Zod input schema for the tool: optional 'enabled' boolean.{ enabled: z.boolean(), },
- src/tools/simulator.ts:95-180 (registration)Registration function that calls server.tool('list_sims') to register the tool with schema and inline handler.export function registerListSimulatorsTool(server: McpServer): void { server.tool( 'list_sims', 'Lists available iOS simulators with their UUIDs. ', { enabled: z.boolean(), }, async (): Promise<ToolResponse> => { log('info', 'Starting xcrun simctl list devices request'); try { const command = ['xcrun', 'simctl', 'list', 'devices', 'available', '--json']; const result = await executeCommand(command, 'List Simulators'); if (!result.success) { return { content: [ { type: 'text', text: `Failed to list simulators: ${result.error}`, }, ], }; } try { const simulatorsData = JSON.parse(result.output); let responseText = 'Available iOS Simulators:\n\n'; for (const runtime in simulatorsData.devices) { const devices = simulatorsData.devices[runtime]; if (devices.length === 0) continue; responseText += `${runtime}:\n`; for (const device of devices) { if (device.isAvailable) { responseText += `- ${device.name} (${device.udid})${device.state === 'Booted' ? ' [Booted]' : ''}\n`; } } responseText += '\n'; } responseText += 'Next Steps:\n'; responseText += "1. Boot a simulator: boot_sim({ simulatorUuid: 'UUID_FROM_ABOVE' })\n"; responseText += '2. Open the simulator UI: open_sim({ enabled: true })\n'; responseText += "3. Build for simulator: build_ios_sim_id_proj({ scheme: 'YOUR_SCHEME', simulatorId: 'UUID_FROM_ABOVE' })\n"; // Example using project variant responseText += "4. Get app path: get_sim_app_path_id_proj({ scheme: 'YOUR_SCHEME', platform: 'iOS Simulator', simulatorId: 'UUID_FROM_ABOVE' })"; // Example using project variant return { content: [ { type: 'text', text: responseText, }, ], }; } catch { return { content: [ { type: 'text', text: result.output, }, ], }; } } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); log('error', `Error listing simulators: ${errorMessage}`); return { content: [ { type: 'text', text: `Failed to list simulators: ${errorMessage}`, }, ], }; } }, ); }
- src/utils/register-tools.ts:123-127 (registration)Tool registration entry in the toolRegistrations array that conditionally registers registerListSimulatorsTool based on env var.{ register: registerListSimulatorsTool, groups: [ToolGroup.SIMULATOR_MANAGEMENT, ToolGroup.PROJECT_DISCOVERY], envVar: 'XCODEBUILDMCP_TOOL_LIST_SIMULATORS', },