Hyprland desktop bridge
Local stdio MCP server for Hyprland 0.56+, using grim, hyprctl, ydotool,
wtype, and xdotool. Registered as hyprland_desktop in the Linux Codex config.
The shared skill is ~/.agents/skills/hyprland-computer-use/SKILL.md.
The server starts on demand as the logged-in user. It has no network listener, shell-command tool, or arbitrary file-write tool. It inherits the graphical session environment through the MCP config. The agent's normal sandbox remains enabled. Focus checks and coordinate validation reduce misdirected input but do not isolate apps or prevent desktop-wide keyboard shortcuts. Use one desktop task at a time.
The existing user ydotool.service owns a mode-0600 socket at
$XDG_RUNTIME_DIR/.ydotool_socket. This machine already grants the active user access
to /dev/uinput through its installed Steam input udev rule. No new root service,
input-group membership, or system-wide permission rule was added.
Maintenance
Inspect input service state with systemctl --user status ydotool.service.
If input stops after system package changes, check /dev/uinput and its ACL before
changing permissions. Stop input injection with systemctl --user stop ydotool.service;
other programs using that shared service will also lose synthetic mouse input.
To disable this MCP bridge, set enabled = false in its Codex config section and
restart the client.
Dependencies are pinned in requirements.lock. Recreate the environment with:
cd ~/.codex/bridges/hyprland-desktop
uv venv .venv --python 3.13
uv pip sync --python .venv/bin/python requirements.lock
Verification
These commands briefly operate a temporary test window on the live desktop. Keep local mouse and keyboard input idle during the run.
.venv/bin/python test_desktop.py
.venv/bin/python test_desktop.py --native
The first tests XWayland with Tk; the second tests native Wayland with GTK 4.
They exercise the MCP handshake and tool calls, Unicode text, selection shortcuts,
clicks, wheel input, dragging, PNG capture, input validation, and the focus guard.
The latest screenshot is /tmp/hyprland-desktop-verified.png.
Test fixtures require the system Python Tk and PyGObject/GTK packages.