Hypruse MCP Server

Computer use for Hyprland: semantic desktop state over IPC, plus vision and native input

Local serverstdioPython

What is the Hypruse MCP Server?

Computer use for Hyprland: semantic desktop state over IPC, plus vision and native input

What the server does

Computer use exists on macOS and Windows. On Linux there is effectively nothing: the Claude Desktop Linux beta explicitly ships without screen control, Anthropic's reference implementation is an X11 container, and the existing Wayland attempts lean on setuid uinput hacks or GNOME-only portals.

  • Semantic first. — desktop returns the real window/workspace tree (addresses, classes, titles, geometry) in one call. The agent switches workspaces and focuses windows the way you do (instantly, over IPC), not by squinting at pixels
  • Vision when it matters. — Screenshots of a monitor, an exact window crop, or a zoomed region, with the geometry/scale metadata to map any pixel back to a clickable coordinate: a coarse-to-fine loop grounded in the GUI-agents research
  • Native input. — Clicks and scrolls are spoken directly over the Wayland wire (zwlr_virtual_pointer_v1); typing goes through wtype's virtual keyboard with a proper XKB keymap, unicode-safe on any layout

More MCP options

Compare MCP servers by category, or browse hosted MCP servers if you prefer an endpoint over a local process.

Maintainer setup documentation.

Recorded tools

Check the linked publisher documentation and your connected client's tool list. Names and availability can vary with the server version and account permissions.

ToolWhat it does
desktopOne-call semantic snapshot: monitors, workspaces, windows (address/class/title/geometry), active window, cursor, and layer surfaces (launchers, bars, notificati
screenshotFocused monitor, exact window crop by address, or x,y,WxH region; returns image + coordinate-mapping metadata; fast JPEG by default (lossless=true for PNG); sta
zoomNative-resolution re-capture around an estimated point (optionally clamped to a window): the precision step before clicking small controls, same metadata contra
uiRead a window's accessibility tree (AT-SPI, GTK/Qt apps that expose one) and return clickable elements by name with exact global coordinates, no screenshot; rep
marksSet-of-Marks capture: the window screenshot with every accessible control drawn as a numbered mark, plus a JSON legend (role, name, current value, exact click p
click_uiClick a control by accessible NAME or by a marks number in one call: the coordinate comes from the tree, the click goes through the real pointer (visible, same
pointermove / click / drag / scroll (discrete wheel notches) in global coordinates
keyboardType literal text (unicode-safe) or press app-level combos (ctrl+shift+t, esc, F5); optional window address focuses the target first so keystrokes land in the r
hyprSwitch workspace, focus/move/close windows, fullscreen, floating (pure IPC, milliseconds; close_window also waits up to 1s for the destroy event, so its result
launchStart an app (optionally silent on another workspace), block on its actual openwindow event, return its address; detects single-instance apps (browsers) whose w
bindsThe user's own keybinds, decoded (SUPER+Q, action, description); the agent runs one with use_bind
use_bindExecute a keybind by combo (SUPER+F), running its bound action, so the agent drives the owner's own launchers and shortcuts. Not available for binds in a Lua hy
sequenceRun an ordered list of actions (pointer/keyboard/click_ui/hypr/wait_for) in one call; stops the moment the desktop changes in a way the current step did not exp
wait_forBlock on real compositor events (window open/close, workspace change, title change, layer surfaces appearing/closing, urgency, screen sharing on/off) with a mat
clipboardRead or write the text clipboard via wl-clipboard; opt-in, exists only with HYPRUSE_CLIPBOARD=1 in the server env

How to install the Hypruse MCP Server

{
  "mcpServers": {
    "hypruse": {
      "command": "uvx",
      "args": [
        "hypruse"
      ],
      "env": {
        "HYPRUSE_SCREENSHOT_MODE": "image"
      }
    }
  }
}

From the project documentation. Replace placeholders and example paths before connecting.

Configuration

VariableDescriptionRequired
HYPRUSE_SCREENSHOT_MODEDeclared in the maintainer’s client configuration.Check documentation

Example prompts to try

  • “Use Hypruse to desktop.”
  • “Use Hypruse to screenshot.”
  • “Use Hypruse to zoom.”

Frequently asked questions

Computer use for Hyprland: semantic desktop state over IPC, plus vision and native input Confirm the tools offered by your installed version in the connected client. Tool availability and permissions depend on the server and account configuration.