screenshot
Capture screen images with coordinate mapping for Hyprland desktop automation. Supports full desktop, window, or region capture and provides pixel-to-screen coordinate conversion for mouse tools.
Instructions
Take a screenshot and return it as an inline image with coordinate mapping.
Returns the image AND a coordinate mapping guide so you can convert image pixel positions to absolute screen coordinates for mouse tools.
Supports three capture modes:
Full desktop/monitor (default): overview at reduced resolution
Window: capture a specific window by class/title
Region: capture a specific rectangle at higher resolution
Args: monitor: Capture a specific monitor (e.g. "DP-1"). Default: all monitors. window: Capture a specific window by selector (e.g. "class:firefox") region: Capture a region as "X,Y WxH" (e.g. "100,200 800x600") max_width: Maximum output width in pixels (default 1024, lower = smaller output) quality: JPEG quality 1-100 (default 60, lower = smaller output) include_cursor: Whether to include the cursor in the screenshot
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| monitor | No | ||
| window | No | ||
| region | No | ||
| max_width | No | ||
| quality | No | ||
| include_cursor | No |
Implementation Reference
- hyprland_mcp/screenshot.py:138-177 (handler)The actual implementation of taking a screenshot and preparing the coordinate mapping.
async def take_screenshot( monitor: str | None = None, window: str | None = None, region: str | None = None, max_width: int = 1024, quality: int = 60, include_cursor: bool = False, ) -> tuple[Image, str]: """Capture a screenshot, resize to fit max_width. Returns (Image, coordinate_info_string) where coordinate_info_string explains how to map image pixel positions to absolute screen coordinates. """ png_bytes, origin_x, origin_y = await capture_raw( monitor=monitor, window=window, region=region, include_cursor=include_cursor, ) # Get native dimensions before resize native_img = PILImage.open(io.BytesIO(png_bytes)) native_w, native_h = native_img.width, native_img.height image, scale = resize_and_compress(png_bytes, max_width=max_width, quality=quality) # Build coordinate mapping info img_w = int(native_w * scale) if scale != 1.0 else native_w img_h = int(native_h * scale) if scale != 1.0 else native_h inv_scale = 1.0 / scale if scale != 1.0 else 1.0 coord_info = ( f"Coordinate mapping: This {img_w}x{img_h} image covers screen region " f"starting at absolute ({origin_x}, {origin_y}), " f"native size {native_w}x{native_h}.\n" f"To convert image coordinates to absolute screen coordinates:\n" f" screen_x = image_x * {inv_scale:.2f} + {origin_x}\n" f" screen_y = image_y * {inv_scale:.2f} + {origin_y}\n" f"IMPORTANT: Always use absolute screen coordinates with mouse tools, " f"never raw image pixel positions." ) return image, coord_info - hyprland_mcp/server.py:378-413 (registration)The registration of the "screenshot" tool in the MCP server.
async def screenshot( monitor: str | None = None, window: str | None = None, region: str | None = None, max_width: int = 1024, quality: int = 60, include_cursor: bool = False, ) -> list: """Take a screenshot and return it as an inline image with coordinate mapping. Returns the image AND a coordinate mapping guide so you can convert image pixel positions to absolute screen coordinates for mouse tools. Supports three capture modes: - Full desktop/monitor (default): overview at reduced resolution - Window: capture a specific window by class/title - Region: capture a specific rectangle at higher resolution Args: monitor: Capture a specific monitor (e.g. "DP-1"). Default: all monitors. window: Capture a specific window by selector (e.g. "class:firefox") region: Capture a region as "X,Y WxH" (e.g. "100,200 800x600") max_width: Maximum output width in pixels (default 1024, lower = smaller output) quality: JPEG quality 1-100 (default 60, lower = smaller output) include_cursor: Whether to include the cursor in the screenshot """ from . import screenshot as ss image, coord_info = await ss.take_screenshot( monitor=monitor, window=window, region=region, max_width=max_width, quality=quality, include_cursor=include_cursor, ) return [image, coord_info]