capture_window
Take screenshots of specific macOS windows by ID using yabai integration, returning base64-encoded PNG images for AI assistant workflows.
Instructions
Capture a screenshot of a specific window by its ID. Returns the image as base64-encoded PNG. Use list_windows first to get window IDs.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| window_id | Yes | The window ID to capture (from list_windows) | |
| include_shadow | No | Include window shadow in the capture |
Input Schema (JSON Schema)
{
"properties": {
"include_shadow": {
"default": true,
"description": "Include window shadow in the capture",
"type": "boolean"
},
"window_id": {
"description": "The window ID to capture (from list_windows)",
"type": "integer"
}
},
"required": [
"window_id"
],
"type": "object"
}
Implementation Reference
- capture_win_mcp/server.py:143-241 (handler)Main handler function that implements the capture_window tool logic: validates input, finds the window using tracker, runs macOS screencapture command to screenshot the window, encodes the PNG as base64, and returns ImageContent with text description.async def handle_capture_window(arguments: dict) -> list[ImageContent | TextContent]: """Handle capture_window tool call.""" try: window_id = arguments.get("window_id") include_shadow = arguments.get("include_shadow", True) if window_id is None: return [ TextContent( type="text", text="Error: window_id is required" ) ] # Refresh tracker to verify window exists tracker.refresh() window = tracker.get_window_by_id(window_id) if not window: return [ TextContent( type="text", text=f"Error: Window with ID {window_id} not found" ) ] # Create temporary file for screenshot temp_file = Path(f"/tmp/capture_win_{window_id}.png") # Build screencapture command cmd = ["screencapture", "-x"] # -x: no sound if not include_shadow: cmd.append("-o") # -o: no shadow cmd.extend(["-l", str(window_id)]) # -l: capture window by ID cmd.append(str(temp_file)) # Capture the window result = subprocess.run( cmd, capture_output=True, text=True, timeout=10 ) if result.returncode != 0: return [ TextContent( type="text", text=f"Error capturing window: {result.stderr}" ) ] # Read and encode the image if not temp_file.exists(): return [ TextContent( type="text", text="Error: Screenshot file not created" ) ] image_data = temp_file.read_bytes() base64_image = base64.b64encode(image_data).decode('utf-8') # Clean up temporary file temp_file.unlink() # Get window details for context app_name = window.get('app', 'Unknown') title = window.get('title', '(Untitled)') return [ TextContent( type="text", text=f"Captured window: [{app_name}] {title} (ID: {window_id})" ), ImageContent( type="image", data=base64_image, mimeType="image/png" ) ] except subprocess.TimeoutExpired: return [ TextContent( type="text", text="Error: Screenshot capture timed out" ) ] except Exception as e: return [ TextContent( type="text", text=f"Error capturing window: {str(e)}" ) ]
- capture_win_mcp/server.py:45-63 (schema)Tool schema definition including input schema for window_id (required integer) and optional include_shadow boolean.Tool( name="capture_window", description="Capture a screenshot of a specific window by its ID. Returns the image as base64-encoded PNG. Use list_windows first to get window IDs.", inputSchema={ "type": "object", "properties": { "window_id": { "type": "integer", "description": "The window ID to capture (from list_windows)" }, "include_shadow": { "type": "boolean", "description": "Include window shadow in the capture", "default": True } }, "required": ["window_id"] } )
- capture_win_mcp/server.py:73-74 (registration)Registration/dispatch logic in the call_tool handler that routes capture_window calls to the handle_capture_window function.elif name == "capture_window": return await handle_capture_window(arguments)