About hypruse
hypruse is an MCP server in the Other category: computer use for Hyprland: semantic desktop state over IPC, plus vision and native input.
Install
uvx
uvx hyprusepip
pip install hypruseThis server has no ConduID identity, so agent calls to it are not receipted. Pin the version you install and review the source before granting it credentials.
Tools (15)
bindsThe user's own keybinds, decoded (`SUPER+Q`, action, description); the agent runs one with `use_bind`
Parameters not published.
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 safety guarantees); an ambiguous name returns the candidates instead of guessing
Parameters not published.
clipboardRead or write the text clipboard via `wl-clipboard`; opt-in, exists only with `HYPRUSE_CLIPBOARD=1` in the server env
Parameters not published.
desktopOne-call semantic snapshot: monitors, workspaces, windows (address/class/title/geometry), active window, cursor, and layer surfaces (launchers, bars, notification popups) with a best-effort kind and geometry. A listed layer is one the compositor tracks, not one you can see: transparent and dormant surfaces are reported too, so screenshot when visibility matters
Parameters not published.
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 and `then=` observation reflect the close instead of racing it)
Parameters not published.
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 right app. Compositor binds (`super+...`) go through `use_bind`, not here
Parameters not published.
launchStart an app (optionally silent on another workspace), block on its actual `openwindow` event, return its address; detects single-instance apps (browsers) whose window ignores exec rules and moves it to the requested workspace
Parameters not published.
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 point per number); needs ImageMagick for the drawing, degrades to the legend alone without it
Parameters not published.
pointermove / click / drag / scroll (discrete wheel notches) in global coordinates
Parameters not published.
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); `stable=true` waits for the frame to settle
Parameters not published.
Show all 15 tools
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 expect, so a click/type/enter micro-sequence costs one round-trip instead of several
Parameters not published.
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; reports current values too (typed text, slider position, checkbox state); falls back to vision when an app exposes nothing
Parameters not published.
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 `hyprland.lua`: those are anonymous closures Hyprland exposes no way to call, so `binds` shows them as action `lua` and `use_bind` says so instead of failing cryptically
Parameters not published.
wait_forBlock on real compositor events (window open/close, workspace change, title change, layer surfaces appearing/closing, urgency, screen sharing on/off) with a match filter and timeout; a filtered wait whose condition already holds (window already gone, workspace already active, layer already mapped) answers instantly with `already: true` instead of missing an event that fired before it subscribed. Replaces sleep-and-hope in multi-step automations
Parameters not published.
zoomNative-resolution re-capture around an estimated point (optionally clamped to a window): the precision step before clicking small controls, same metadata contract
Parameters not published.
Ask AI
✦
Ask AI about hypruse
Powered by Claude · Grounded in docs
I know everything about hypruse. Ask me about installation, configuration, usage, or troubleshooting.
Security checks
6 checks have not been run yet.