MCP iOS Simulator Screenshot

Instructions

Implementation Reference

• src/services/screenshot-service.ts:32-77 (handler)

  Core handler function that executes the screenshot capture logic: validates device, captures using xcrun simctl, saves, resizes with sharp, and returns metadata.
  public async captureScreenshot(options: ScreenshotOptions = {}): Promise<ScreenshotResult> { try { // Prepare file paths const { outputPath } = this.prepareFilePaths(options); // Validate device ID (only if specified) if (options.deviceId && options.deviceId !== 'booted') { const isValid = await this.deviceValidator.isValidDeviceId(options.deviceId); if (!isValid) { throw new Error(`Invalid device ID: ${options.deviceId}. Please use a valid device ID or 'booted'.`); } } // Capture screenshot from simulator const imageBuffer = await this.captureSimulatorScreenshot(options.deviceId); // Save the image await fs.writeFile(outputPath, imageBuffer); // Process the image (resize if needed) const finalPath = options.resize !== false ? await this.resizeImage(outputPath, options.maxWidth || config.screenshot.defaultMaxWidth) : outputPath; // Get image metadata const metadata = await this.getImageMetadata(finalPath); // Get command line arguments const outputDir = this.outputManager.isUsingRootDirectoryDirectly() ? this.outputManager.getRootDirectory() : undefined; return { success: true, message: 'iOS Simulator screenshot saved successfully', filePath: finalPath, metadata, serverConfig: { commandLineArgs: { outputDir } } }; } catch (error) { return this.createErrorResult(error); } }
• src/index.ts:192-218 (handler)

  MCP tool call handler that maps request parameters to ScreenshotOptions and delegates to ScreenshotService.captureScreenshot.
  private async handleScreenshotRequest(request: any): Promise<any> { try { const args = request.params.arguments as Record<string, unknown> || {}; // Map API parameters to internal options const options: ScreenshotOptions = { outputFileName: args.output_filename as string, outputDirectoryName: args.output_directory_name as string, resize: args.resize as boolean, maxWidth: args.max_width as number, deviceId: args.device_id as string }; // Capture screenshot const result = await this.screenshotService.captureScreenshot(options); // Return formatted response return this.createMcpResponse(result); } catch (error) { const err = error as Error; return this.createMcpResponse({ success: false, message: `Error: ${err.message}`, error: { code: 'UNEXPECTED_ERROR' } }); } }
• src/index.ts:153-187 (schema)

  Defines the tool schema including inputSchema with properties for filename, directory, resize options, and device ID.
  private getScreenshotToolDefinition() { return { name: 'get_screenshot', description: 'Capture a screenshot from iOS Simulator', inputSchema: { type: 'object', properties: { output_filename: { type: 'string', description: 'Output filename (if not specified, timestamp.png will be used)' }, output_directory_name: { type: 'string', description: 'Subdirectory name for screenshots (if not specified, .screenshots will be used)', default: config.screenshot.defaultOutputDirName }, resize: { type: 'boolean', description: 'Whether to resize the image to approximately VGA size', default: true }, max_width: { type: 'integer', description: 'Maximum width for resizing (pixels)', default: config.screenshot.defaultMaxWidth }, device_id: { type: 'string', description: 'Specify a simulator device (if not specified, the booted device will be used)' } }, required: [] } }; }
• src/index.ts:133-135 (registration)

  Registers the get_screenshot tool by including it in the ListTools response.
  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [this.getScreenshotToolDefinition()] }));
• src/index.ts:139-141 (handler)

  Dispatch logic in CallToolRequestSchema handler that routes get_screenshot calls to the specific handler.
  if (request.params.name === 'get_screenshot') { return await this.handleScreenshotRequest(request); } else {