hypr-cua-mcp
Provides tools to control and inspect the Hyprland compositor: list windows and outputs, take screenshots, focus windows, launch applications, manage workspaces, toggle floating windows, send layout messages, and run raw dispatchers.
Provides tools to drive terminals in detached tmux sessions on an isolated hypr-cua socket, enabling background command execution and interaction without stealing window focus.
Provides computer-use capabilities on Wayland sessions: screenshots via grim, clipboard access via wl-clipboard, and absolute pointer/keyboard input via uinput, with coordinates mapped from screenshots to the compositor's global layout.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
hypr-cua-mcp
A Hyprland/Wayland computer-use MCP server. It gives an MCP client (Claude Code, etc.) the ability to see your desktop, understand it via the Hyprland tree, and drive it with mouse + keyboard. It runs locally over stdio.
Why this exists: generic Linux computer-use servers are blind to the compositor —
they hand the model a giant multi-monitor screenshot and hope its pixel guesses
land. This server crops to one output (or one window) with grim, downscales to
the vision-API budget, and exposes hyprctl's tree so the model targets windows
by identity, not luck. Coordinates are always given in the screenshot the model
was just shown; the server maps them back to global layout pixels.
Built for Wayland/Hyprland: grim (capture) + a self-owned uinput device
(input) + hyprctl (tree/control) + wl-clipboard. It is the Wayland successor
to i3-computer-use-mcp (X11).
Tools
Window ids are Hyprland addresses (0x…) from list_windows — not integers.
See
Tool | What it does |
| Every Hyprland window: id (address), class, title, workspace, output, global rect, floating/focus/visibility |
| Active monitors: global geometry, scale, workspace |
| Screenshot one output (default: focused), downscaled to the API budget |
| Full-res crop of a single window (by address) — best for small text |
| Current global pointer location |
Act
Tool | What it does |
| Pointer actions; coords in a screenshot's pixel space (pass its |
| Keyboard input; with a |
| Exact text in/out of the |
Control Hyprland (needs a Lua config, see Requirements)
Tool | What it does |
| Focus a window by address (best-effort; see the follow_mouse caveat under Safety) |
| Launch an app via Hyprland's exec dispatcher |
| Switch to / move a window (by address) to a workspace |
| Toggle a window's floating state |
| Send a message to the active layout engine (e.g. |
| Raw Hyprland dispatcher escape hatch ( |
Work off-screen (no window, no focus stolen)
Tool | What it does |
| Drive terminals in detached tmux sessions on an isolated |
| Run a command as a background task and poll it ( |
| Drive Chrome tabs over the DevTools protocol, never your main profile (see Browser channel) |
Related MCP server: Omarchy Computer MCP
The coordinate model (the important bit)
The Hyprland tree uses global layout pixels spanning all monitors. Screenshots are cropped + downscaled, so every screenshot records a mapping frame (region origin + per-axis scale). Pointer tools accept coordinates in the screenshot's pixel space and translate them:
global_x = region.x + screenshot_x / scale_x
global_y = region.y + screenshot_y / scale_yPractically: take a screenshot (it returns a frame_id), then call
click(x, y, frame_id=…) with the pixel you see in that image. Pointer tools
reject a stale or unknown frame_id rather than guessing against the wrong one.
Without a frame_id, they use your latest screenshot.
The uinput pointer positions absolutely: global pixels map to the device's abs
axes via the layout extent read from hyprctl monitors (verified ~1px).
Requirements
Hyprland on Wayland. Developed and tested on Hyprland 0.56 across three monitors at scale 1.
A Lua config (
hyprland.lua, Hyprland 0.55+) for the window-control tools. These tools go throughhyprctl evaland Hyprland's Luahl.dispatchAPI:focus_window,launch,goto_workspace,move_window_to_workspace,set_floating,layout_message,run_dispatch, plustype_text/keywith acon_idandmove_mouse(follow=True). Everything else works with any config: screenshots, pointer and keyboard input, the window tree, the clipboard, and the tmux/task/browser channels.Read-write access to
/dev/uinputfor mouse and keyboard input (see below).Python 3.11+ and
uv.It runs inside your Hyprland session: it needs
WAYLAND_DISPLAY,XDG_RUNTIME_DIRandHYPRLAND_INSTANCE_SIGNATUREfrom the environment. MCP clients launched from your desktop pass these through.
Install the dependencies
The server shells out to a handful of CLI tools. screenshot needs grim, the
clipboard tools need wl-clipboard, and everything reads/drives Hyprland through
hyprctl; tmux and a Chromium/Chrome are only needed for the optional terminal
and browser channels.
Tool | Needed for | Arch | Debian/Ubuntu |
| tree + control (required) | bundled with | bundled with |
|
|
|
|
|
|
|
|
| runs the server + syncs Python deps |
| see astral.sh/uv |
|
|
|
|
Chromium / Chrome |
|
|
|
Arch, in one go (Hyprland assumed already installed):
sudo pacman -S grim wl-clipboard uv tmux chromiumInput uses a self-owned uinput device, so the process needs read-write on
/dev/uinput. It needs no root and no ydotoold. Run getfacl /dev/uinput. If it
lists your user with rw (typically through a uaccess udev rule), you're set. If
not, add a rule that grants access to the user logged in at the seat:
echo 'KERNEL=="uinput", SUBSYSTEM=="misc", TAG+="uaccess", OPTIONS+="static_node=uinput"' \
| sudo tee /etc/udev/rules.d/60-hypr-cua-uinput.rules
sudo udevadm control --reload && sudo udevadm triggerThe Python deps (mcp, pillow, evdev, websocket-client) are synced by uv
on first launch.
Miss one and the matching tool says so: calling screenshot without grim
returns "grim not found; install it …" straight to the model, so it can tell you
what to install instead of failing on a cryptic traceback.
Register with your MCP client
It's a local stdio server. The client starts it on demand, and you don't need a clone.
Claude Code:
claude mcp add hypr-cua -- uvx hypr-cua-mcpClients with an mcpServers JSON config (Cursor, Gemini CLI, Cline, …):
{
"mcpServers": {
"hypr-cua": {
"command": "uvx",
"args": ["hypr-cua-mcp"]
}
}
}Codex CLI (~/.codex/config.toml):
[mcp_servers.hypr-cua]
command = "uvx"
args = ["hypr-cua-mcp"]From a local checkout: the wrapper syncs deps on first launch. When a shared server is running, the wrapper connects to it.
claude mcp add hypr-cua -- /path/to/hypr-computer-use-mcp/bin/hypr-cua-mcpReconnect your client (in Claude Code: /mcp → reconnect) to pick up the server.
Smoke-test the plumbing first (read-only, no clicks):
uvx hypr-cua-mcp --selftestOne shared server per login
By default each MCP client session starts its own hypr-cua. From a checkout you can
run one shared server per desktop login instead. A session then connects in
about 20 ms and costs about 17 MB instead of about 94 MB. bin/hypr-cua-mcp
connects to the shared server when it runs. When it doesn't, the wrapper starts a
stdio server for the session, so the registration stays the same.
Install the units. Run this in the checkout:
uv sync mkdir -p ~/.config/systemd/user cp contrib/systemd/hypr-cua.socket ~/.config/systemd/user/ sed "s|@CHECKOUT@|$PWD|" contrib/systemd/hypr-cua.service > ~/.config/systemd/user/hypr-cua.service systemctl --user daemon-reloadStart the socket from your Hyprland startup, so each new server gets the current session's variables. In
hyprland.lua, inside your startup handler:hl.exec_cmd("systemctl --user import-environment DISPLAY WAYLAND_DISPLAY HYPRLAND_INSTANCE_SIGNATURE XDG_CURRENT_DESKTOP; systemctl --user stop hypr-cua.service; systemctl --user restart hypr-cua.socket")Run the same command in a terminal once to start it without logging out.
Reconnect your MCP sessions (in Claude Code:
/mcp→ reconnect).
To upgrade, run git pull && uv sync && systemctl --user restart hypr-cua.service.
Open sessions reconnect by themselves. A call that was running during the restart
fails once with a message that it may have completed. The restart also ends
hypr-cua's tmux sessions and tasks.
Sessions share the server's browser. Its HYPR_CUA_CDP_* settings come from the
service's Environment= lines, not from the client. Screenshots stay per session:
the server rejects another session's frame_id as stale.
Browser channel
The cdp_* tools drive Chrome or Chromium tabs over the DevTools protocol, so
browser work needs no window focus. They never open your main profile.
The first cdp_* call picks a browser, and later calls keep it while it stays up:
If a browser answers on port 9222, the tools attach to it. Run your automation profile there to keep logins.
Otherwise they start a private headless Chrome with a throwaway profile. Chrome picks a free port, so it never collides with 9222. It stops after 10 minutes without a call, and when the server exits.
cdp_targets reports which one is in use, "browser": "automation" or
"private". All sessions of one server share that browser, its tabs and its
cookies.
For logins that persist, start a dedicated automation profile on port 9222. From a
checkout, bin/hypr-cua-chrome does that. Otherwise run:
chromium --user-data-dir="$HOME/.local/share/hypr-cua-chrome" \
--remote-debugging-port=9222 --no-first-run --no-default-browser-checkLog in only to what you're happy to automate. Any local process that can reach a DevTools port can drive that browser, and that includes the private one.
cdp_open and cdp_navigate wait for the page's load event, and for a CSS
selector if you pass wait_for. A page still loading at timeout (default 30 s)
comes back with "timed_out": true instead of an error. cdp_read takes a
selector and max_chars. cdp_screenshot returns an image of a tab's viewport.
Variable | Default | Effect |
|
| Port of the automation browser to attach to |
|
|
|
| first Chrome/Chromium on | Browser binary for the private Chrome |
|
| Profile directory for |
Set them in your client's server config. In Claude Code:
claude mcp add hypr-cua -e HYPR_CUA_CDP_AUTOLAUNCH=0 -- uvx hypr-cua-mcp. In JSON
configs, add an "env": {…} block next to command.
Safety
No auth — it's a local stdio server. Don't expose it over a socket.
There is no sandbox on Wayland: it drives your real desktop and can click anything you can — terminals with sudo, your password manager, Slack, email. Supervise live runs.
Emergency stop: kill the MCP server (its uinput device dies with it).
follow_mouse=1caveat: Hyprland keyboard focus tracks the pointer, sofocus_window(address)is best-effort — the reliable way to focus a window for typing is to click it via screenshot coordinates.type_text(con_id=…)raises rather than typing into an unverified window.Input is real uinput, so it resets the compositor idle timer naturally (no synthetic-input self-lock, unlike X11). See
docs/gotchas.md.
Known limitations
Typing is US-ASCII only:
type_textskips any other character. For anything else,write_clipboardand paste.Capture on monitors with scale ≠ 1 is untested, and the crop is likely off there.
The synthetic pointer doesn't hover-focus. Click to focus, or use
move_mouse(follow=True).cdp_click/cdp_typeinject JavaScript, so pages that insist on trusted input events won't react.
Details, plus the task runner's edge cases:
KNOWN-ISSUES.md.
Project status
Stable and maintained. hypr-cua-mcp does what it set out to do, so the commit log is quiet on purpose. Expect bug fixes, Hyprland-compatibility updates and dependency bumps, not a stream of new features. A quiet repo here means done, not abandoned. Issues and PRs still get answered.
Contributing
Bug reports and fixes are welcome; for anything bigger, open an issue first. See
CONTRIBUTING.md,
and AGENTS.md
for setup, tests, and the Hyprland conventions that bite.
Registry
On PyPI as hypr-cua-mcp and in the MCP
registry as com.smirnovlabs/hypr-cua-mcp (manifest:
server.json).
mcp-name: com.smirnovlabs/hypr-cua-mcp
License
MIT — see LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Eyes and hands on real Windows PCs — observe, click, type via Glasswarp API.
Melaya is a remote MCP server. It gives an assistant hands on your own Android phone and browser: it reads the screen through the accessibility tree, then taps, types and navigates inside the apps and sites you allow-list, with no per-app API. It also builds, schedules and runs agent pipelines across 6k+ connected tools. OAuth 2.1, nothing to install.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceMCP server for controlling Hyprland Wayland compositor: screen capture, mouse/keyboard injection, and automation via native Hyprland IPC and wlr protocols.MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to inspect and control an Omarchy/Hyprland desktop by taking screenshots, focusing windows, moving/clicking the mouse, scrolling, typing text, and sending keyboard shortcuts.MIT
- AlicenseAqualityBmaintenanceEnables AI agents to control Hyprland desktops via MCP, including pointer/keyboard input, screenshots, launching apps, and natural-language window targeting using a local decision model.141MIT
- AlicenseNot gradedqualityFmaintenanceAn MCP server that lets agents observe and control an Omarchy or Hyprland desktop: list monitors, windows, workspaces, and accessibility controls, capture screenshots, then move the pointer, type text, send shortcuts, and manage windows and workspaces. It works over stdio with any MCP client, guarding actions with session-lock and single-driver checks while treating on-screen content as untrusted data.Apache 2.0