Hyprland Computer Use — Claude Code MCP server setup
Lets coding agents drive a Wayland desktop on Hyprland using grim screenshots, hyprctl window inspection, and uinput actions.
claude mcp add hypr-cua-mcp -- uvx hypr-cua-mcpWhat Hyprland Computer Use does
Desktop automation often treats Linux displays as an unstructured canvas, struggling across multi-monitor setups. This server reads the compositor layout directly via hyprctl and uses grim to capture either an output or an individual window. Each screenshot produces an image downscaled for the model along with a frame identifier, letting pointer tools translate screenshot coordinates back to absolute layout pixels.
Keyboard strokes and pointer movements pass through a virtual device in /dev/uinput. Window management tools such as workspace switching require Hyprland 0.55 or newer configured with Lua. For work that should not disturb the user pointer, the server provides separate tmux terminal sessions and a Chrome DevTools protocol bridge.
What it helps with
- inspect and focus windows on Hyprland using compositor addresses
- capture downscaled screenshots of single outputs or windows via grim
- simulate keyboard and mouse events using a native uinput device
- run terminal tasks in detached tmux sessions without stealing focus
Example prompts for the agent
- Take a screenshot of the active window and click the submit button
- List all open windows on Hyprland and move the editor to workspace 2
- Read the current Wayland clipboard selection and print its contents
How to install Hyprland Computer Use
Platform CLI
claude mcp add hypr-cua-mcp -- uvx hypr-cua-mcpuvx runs the command named after the package; if the README names another one, use uvx --from hypr-cua-mcp <command>
Platform CLI
codex mcp add hyprland-computer-use -- uvx hypr-cua-mcpuvx runs the command named after the package; if the README names another one, use uvx --from hypr-cua-mcp <command>
Config file
{
"mcpServers": {
"hyprland-computer-use": {
"command": "uvx",
"args": [
"hypr-cua-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from hypr-cua-mcp <command>
Config file
{
"servers": {
"hyprland-computer-use": {
"type": "stdio",
"command": "uvx",
"args": [
"hypr-cua-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from hypr-cua-mcp <command>
Platform CLI
gemini mcp add hyprland-computer-use uvx hypr-cua-mcpuvx runs the command named after the package; if the README names another one, use uvx --from hypr-cua-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Hyprland Computer Use
How to install Hyprland Computer Use in Claude Code?
Run claude mcp add hyprland-computer-use -- uvx hypr-cua-mcp in your terminal. Launch the command from inside your active Hyprland desktop session.
What does Hyprland Computer Use do?
It allows MCP-compatible agents to inspect Hyprland window trees, grab display screenshots, and issue mouse and keyboard actions inside a Wayland environment.
Why does the server require access to /dev/uinput?
Simulated mouse and keyboard events are dispatched through the Linux uinput interface, which requires read and write permissions on /dev/uinput.
