hyprland-mcp-server

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, wid…

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…

Click inside a specific window using coordinates relative to that window. This avoids global-coordinate mistakes when using hyprland_screenshot_window output. Given a local point (local_x, local_y), this tool converts to global coordinates: global_x = window_x + local_x global_y = window_y + lo…

Execute click-at with optional bounded retries, then capture the active window screenshot. This helper implements a practical click → verify loop: 1) click at global coordinates 2) optionally retry nearby nudged points if focus does not match expected window 3) capture and return active-window scre…

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 ge…

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 (…

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. Identify the target window with ONE of: address, class (substring), title (subst…

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. Use this tool when you want to interact with or screenshot whatever the user is looking at.…

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). Returns: { "x": number, …

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…

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. Use hyprland_list_windows to get window geometry (x, y…

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". Args: - include_image (boolean): Embed bas…

Capture a full-monitor screenshot in Hyprland using grim. Captures the entire display output of a single monitor. Useful for capturing the full desktop or when you need to see the complete layout across all windows on that output. Args: - monitor (string): Monitor name like 'DP-1' or 'HDMI-A-1'.…

Capture a screenshot of a specific window in Hyprland using grim. Identify the target window with ONE of: address, class (substring), title (substring), or pid. Prefer `address` for precision; class/title for convenience. Use hyprland_list_windows to discover addresses and classes. The window must…

Send a key or key combination to a specific window or the active window. Uses hyprctl dispatch sendshortcut to inject keyboard events without disturbing focus. The window does not need to be focused — keys can be sent to background windows. For typing plain text strings, use hyprland_type_text ins…

Switch the active workspace on the focused monitor. Accepts either a numeric workspace ID or a workspace name. Use hyprland_list_workspaces to discover available workspaces and their IDs/names. Hyprland also supports special values for 'name': - "previous" → switch to the previously active work…

Type a text string into the currently focused window using wtype. The text is injected directly into the Wayland compositor as keyboard events. The target window must be focused first — use hyprland_focus_window if needed. Supports Unicode characters including emoji. For special keys (Enter, Tab, …

Press a single special key by XKB name in the currently focused window. Uses wtype -k to inject a key event. The window must be focused — use hyprland_focus_window first. For typing text strings use hyprland_type_text. For key combinations with modifiers (Ctrl+C) use hyprland_send_key. Common XKB …