MCP server for capturing screenshots and querying window state in Hyprland Wayland compositor
The Hyprland MCP server demonstrates strong naming conventions and comprehensive parameter descriptions across all 17 tools. Tool names uniformly follow verb_noun patterns (list_windows, screenshot_window, click_at, etc.), making intent clear. However, there are notable gaps in output schema documentation and error handling guidance. Input schemas are well-defined with proper types and descriptions for all parameters. The server excels at composability, tools chain naturally (list_windows → screenshot_window via address). Major weakness: output schemas are not explicitly documented in the source code provided, forcing reliance on implicit JSON inference. Error handling is minimal, tools appear to throw raw exceptions rather than providing actionable recovery guidance. Risk annotations (READ_ONLY, WRITE) are present but not formally expressed in the schema via tool annotations. Several tools accept multiple selector patterns (address, class, title, pid) which creates potential for ambiguity, though descriptions do clarify this is an OR relationship.
Move the cursor to absolute coordinates and perform a mouse click. Requires ydotool and the ydotoold daemon to be running. The cursor is moved to the target position first, then the click is fired. Coordinates are in global layout pixels. Use hyprland_list_windows to get window geometry (x, y, width, height) to compute target coordinates. Use hyprland_get_cursor_pos to verify position after clicking.
Click on a window by targeting its center (with optional offset). Automatically computes the window center from its geometry and performs a click there. Requires ydotool and the ydotoold daemon to be running. Identify the target window with ONE of: address, class (substring), title (substring), or pid. Use hyprland_list_windows to discover available windows.
Move the cursor to absolute coordinates and perform a double mouse click. Requires ydotool and the ydotoold daemon to be running. The cursor is moved to the target position first, then two clicks are fired with a short pause. Coordinates are in global layout pixels. Use hyprland_list_windows to get window geometry (x, y, width, height) to compute target coordinates.
Double-click on a window by targeting its center (with optional offset). Automatically computes the window center from its geometry and performs a double click there. Requires ydotool and the ydotoold daemon to be running. Identify the target window with ONE of: address, class (substring), title (substring), or pid. Use hyprland_list_windows to discover available windows.
Output schemas not explicitly documented. While tool descriptions reference return fields (window address, class, title, PID, workspace, monitor, geometry, flags), there is no formal JSON Schema definition for return types. This forces LLMs to infer structure and wastes tokens on uncertainty.
Multiple selector parameters (address, class, title, pid) in screenshot and click tools create ambiguity. Descriptions say these are alternatives, but there is no formal constraint (e.g., 'at least one required', 'exactly one of') in the schema. LLMs may pass all four or none, causing ambiguous failures.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 58 | 2025-06-18+ | v2 |
| 2026-03-09 | D | 52 | - | v1 |
Bring keyboard and compositor focus to a specific window in Hyprland. Uses hyprctl dispatch focuswindow to focus the target window. After focusing, keyboard input (type_text, send_key) will be directed to that window.
Get metadata for the currently focused (active) window in Hyprland. Returns the same fields as hyprland_list_windows for a single window: address, class, title, PID, workspace, monitor, geometry, and flags.
Get the current cursor (mouse pointer) position in global layout coordinates. Returns the absolute X/Y position of the mouse cursor on the Wayland compositor canvas. Coordinates are in pixels relative to the top-left corner of the global layout (across all monitors).
List all connected monitors in Hyprland with resolution, position, refresh rate, and scale. Use monitor names (e.g. 'DP-1', 'HDMI-A-1') with hyprland_screenshot_monitor.
List all open windows in the Hyprland Wayland compositor with their metadata. Returns window address, class, title, PID, workspace, monitor, geometry (position + size), and flags (floating, pinned, fullscreen, XWayland). The window `address` is the unique identifier required by other tools such as `hyprland_screenshot_window`.
List all workspaces in Hyprland with window counts and monitor assignments. Returns workspace ID, name, monitor name, window count, fullscreen state, and the title of the last focused window in that workspace.
Move the mouse cursor to an absolute position in global layout coordinates. Uses hyprctl dispatch movecursor to reposition the cursor without clicking. Coordinates are in pixels relative to the top-left corner of the Wayland compositor canvas.
Capture a screenshot of the currently focused (active) window in Hyprland. No selector needed — automatically identifies the focused surface via hyprctl activewindow. This is the most convenient way to screenshot "what the user is currently looking at".
Capture a screenshot of an entire monitor in Hyprland. Identify the target monitor by name (e.g. 'DP-1', 'HDMI-A-1'). Use hyprland_list_monitors to discover available monitor names. The screenshot is saved as a PNG file and returned as base64-encoded image data.
Capture a screenshot of a specific window in Hyprland. Identify the target window by address, class (substring), title (substring), or PID. Use hyprland_list_windows to discover available windows and their addresses. The screenshot is saved as a PNG file and returned as base64-encoded image data. Applies monitor scale factor automatically so the captured region matches what you see on screen.
Send a keyboard key press (with modifiers) to the currently focused window in Hyprland. Supports single keys and key combinations with modifiers (Shift, Ctrl, Alt, Super). Requires wtype and a Wayland environment.
Switch to a different workspace in Hyprland. Uses hyprctl dispatch workspace to switch the active workspace. The workspace can be identified by ID (number) or name (string).
Type text into the currently focused window in Hyprland. Sends text character-by-character via wtype to the active window. Requires wtype binary and a Wayland environment.
No error handling guidance. Tools throw raw exceptions (e.g., 'hyprctl failed: <msg>') without actionable recovery paths. Error responses do not tell LLMs what to do next, retry, fix input, check dependencies, or give up. Per the rubric, errors should categorize as retryable vs user-fixable vs fatal and include the invalid value.
Risk annotations (READ_ONLY, WRITE) are marked in the server metadata but NOT formally expressed in tool schemas via readOnlyHint/destructiveHint/idempotentHint. This prevents clients from understanding operation safety and blast radius.
The click_at tool accepts an optional 'window' object for bounds validation but the schema is incomplete, no shape defined for the window object. This leaves the LLM guessing what fields are required or allowed.
No pagination guidance for list tools. hyprland_list_windows and hyprland_list_workspaces return all results without limit, offset, or total_count. Large window counts could exhaust context windows. Screenshot and list tools should document expected result sizes and provide pagination if unbounded.
Response format parameter (markdown vs json) is offered but default markdown may not be ideal for structured agent processing. JSON should be the default; markdown can be an option for human-readable output.