take_screenshot
Capture macOS screenshots of fullscreen, window, or selection with options for format, cursor visibility, window shadow, and timestamped filenames. Save to specified path.
Instructions
Take a screenshot using macOS screencapture
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Image format | |
| hideCursor | No | Whether to hide the cursor | |
| path | Yes | Path where to save the screenshot | |
| shadow | No | Whether to include the window shadow (only for window type) | |
| timestamp | No | Timestamp to add to filename | |
| type | Yes | Type of screenshot to take |
Implementation Reference
- src/features/screenshot.ts:97-125 (handler)Main handler function that validates parameters, builds the screencapture command, executes it, and handles errors.export async function takeScreenshot(params: ScreenshotParams): Promise<void> { try { validateScreenshotParams(params); const command = buildScreenshotCommand(params); await execAsync(command); } catch (error) { if (error instanceof NotificationError) { throw error; } const err = error as Error; if (err.message.includes('execution error')) { throw new NotificationError( NotificationErrorType.COMMAND_FAILED, 'Failed to capture screenshot' ); } else if (err.message.includes('permission')) { throw new NotificationError( NotificationErrorType.PERMISSION_DENIED, 'Permission denied when trying to capture screenshot' ); } else { throw new NotificationError( NotificationErrorType.UNKNOWN, `Unexpected error: ${err.message}` ); } } }
- src/types.ts:65-78 (schema)TypeScript interface defining the input parameters for the take_screenshot tool.export interface ScreenshotParams { /** Path where to save the screenshot */ path: string; /** Type of screenshot to take */ type: 'fullscreen' | 'window' | 'selection'; /** Image format (png, jpg, pdf, tiff) */ format?: 'png' | 'jpg' | 'pdf' | 'tiff'; /** Whether to hide the cursor */ hideCursor?: boolean; /** Whether to include the window shadow (only for window type) */ shadow?: boolean; /** Timestamp to add to filename (defaults to current time) */ timestamp?: boolean; }
- src/index.ts:143-179 (registration)Tool registration in the MCP server's ListTools response, including name, description, and JSON schema for inputs.{ name: 'take_screenshot', description: 'Take a screenshot using macOS screencapture', inputSchema: { type: 'object', properties: { path: { type: 'string', description: 'Path where to save the screenshot', }, type: { type: 'string', enum: ['fullscreen', 'window', 'selection'], description: 'Type of screenshot to take', }, format: { type: 'string', enum: ['png', 'jpg', 'pdf', 'tiff'], description: 'Image format', }, hideCursor: { type: 'boolean', description: 'Whether to hide the cursor', }, shadow: { type: 'boolean', description: 'Whether to include the window shadow (only for window type)', }, timestamp: { type: 'boolean', description: 'Timestamp to add to filename', } }, required: ['path', 'type'], additionalProperties: false, }, },
- src/features/screenshot.ts:7-49 (helper)Helper function to validate the screenshot parameters against expected types and values.function validateScreenshotParams(params: ScreenshotParams): void { if (!params.path || typeof params.path !== 'string') { throw new NotificationError( NotificationErrorType.INVALID_PARAMS, 'Path is required and must be a string' ); } if (!params.type || !['fullscreen', 'window', 'selection'].includes(params.type)) { throw new NotificationError( NotificationErrorType.INVALID_PARAMS, 'Type must be one of: fullscreen, window, selection' ); } if (params.format && !['png', 'jpg', 'pdf', 'tiff'].includes(params.format)) { throw new NotificationError( NotificationErrorType.INVALID_PARAMS, 'Format must be one of: png, jpg, pdf, tiff' ); } if (params.hideCursor !== undefined && typeof params.hideCursor !== 'boolean') { throw new NotificationError( NotificationErrorType.INVALID_PARAMS, 'HideCursor must be a boolean' ); } if (params.shadow !== undefined && typeof params.shadow !== 'boolean') { throw new NotificationError( NotificationErrorType.INVALID_PARAMS, 'Shadow must be a boolean' ); } if (params.timestamp !== undefined && typeof params.timestamp !== 'boolean') { throw new NotificationError( NotificationErrorType.INVALID_PARAMS, 'Timestamp must be a boolean' ); } }
- src/features/screenshot.ts:54-92 (helper)Helper function to construct the screencapture command string based on parameters.function buildScreenshotCommand(params: ScreenshotParams): string { let command = 'screencapture'; // Screenshot type switch (params.type) { case 'window': command += ' -w'; // Capture window break; case 'selection': command += ' -s'; // Interactive selection break; // fullscreen is default, no flag needed } // Optional flags if (params.format) { command += ` -t ${params.format}`; } if (params.hideCursor) { command += ' -C'; // Hide cursor } if (params.type === 'window' && params.shadow === false) { command += ' -o'; // No window shadow } // Add timestamp to filename if requested let path = params.path; if (params.timestamp) { const timestamp = new Date().toISOString().replace(/[:.]/g, '-'); const ext = params.format || 'png'; path = path.replace(new RegExp(`\\.${ext}$`), `-${timestamp}.${ext}`); } command += ` "${escapeString(path)}"`; return command; }