hypruse — Hyprland MCP server: features and installation
hypruse lets an AI agent inspect and control a Hyprland desktop through MCP. Use it to interact with windows and graphical apps from an agent.
claude mcp add --env HYPRUSE_SCREENSHOT_MODE=<HYPRUSE_SCREENSHOT_MODE> --env HYPRUSE_READONLY=<HYPRUSE_READONLY> --env HYPRUSE_CONFINE=<HYPRUSE_CONFINE> --env HYPRUSE_AUTH_GUARD=<HYPRUSE_AUTH_GUARD> --env HYPRUSE_STRICT=<HYPRUSE_STRICT> --transport stdio hypruse -- uvx hypruseWhat hypruse does
hypruse connects an MCP client to a Hyprland desktop. The desktop tool reports monitors, workspaces and windows; screenshot and zoom provide visual context, while ui reads controls exposed through an app’s accessibility tree. Hyprland IPC handles window and workspace operations.
The server can also click controls, enter text and start apps. It uses Wayland input, wtype for keyboard events and grim for screenshots. click_ui targets a control by its accessible name or a number from marks; if a name matches multiple controls, it returns the choices instead of guessing.
Hyprland is required. The ui tool depends on an app exposing accessibility information, and drawing numbered marks requires ImageMagick. In apps without that accessibility tree, the agent has to rely on screenshots.
What it helps with
- inspect Hyprland windows and workspaces
- locate a control by its accessible name
- click a button in a graphical app
- enter text into an application window
- capture a screen or a selected region
Example prompts for the agent
- Show the open windows and active workspace.
- Find the save button in this window and click it.
- Take a screenshot, then enter text in the open window.
How to install hypruse
Platform CLI
claude mcp add --env HYPRUSE_SCREENSHOT_MODE=<HYPRUSE_SCREENSHOT_MODE> --env HYPRUSE_READONLY=<HYPRUSE_READONLY> --env HYPRUSE_CONFINE=<HYPRUSE_CONFINE> --env HYPRUSE_AUTH_GUARD=<HYPRUSE_AUTH_GUARD> --env HYPRUSE_STRICT=<HYPRUSE_STRICT> --transport stdio hypruse -- uvx hypruseReplace <…> with your own values. 6 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from hypruse <command>
Platform CLI
codex mcp add hypruse --env HYPRUSE_SCREENSHOT_MODE=<HYPRUSE_SCREENSHOT_MODE> --env HYPRUSE_READONLY=<HYPRUSE_READONLY> --env HYPRUSE_CONFINE=<HYPRUSE_CONFINE> --env HYPRUSE_AUTH_GUARD=<HYPRUSE_AUTH_GUARD> --env HYPRUSE_STRICT=<HYPRUSE_STRICT> -- uvx hypruseReplace <…> with your own values. 6 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from hypruse <command>
Config file
{
"mcpServers": {
"hypruse": {
"command": "uvx",
"args": [
"hypruse"
],
"env": {
"HYPRUSE_SCREENSHOT_MODE": "<HYPRUSE_SCREENSHOT_MODE>",
"HYPRUSE_READONLY": "<HYPRUSE_READONLY>",
"HYPRUSE_CONFINE": "<HYPRUSE_CONFINE>",
"HYPRUSE_AUTH_GUARD": "<HYPRUSE_AUTH_GUARD>",
"HYPRUSE_STRICT": "<HYPRUSE_STRICT>"
}
}
}
}Replace <…> with your own values. 6 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from hypruse <command>
Config file
{
"servers": {
"hypruse": {
"type": "stdio",
"command": "uvx",
"args": [
"hypruse"
],
"env": {
"HYPRUSE_SCREENSHOT_MODE": "<HYPRUSE_SCREENSHOT_MODE>",
"HYPRUSE_READONLY": "<HYPRUSE_READONLY>",
"HYPRUSE_CONFINE": "<HYPRUSE_CONFINE>",
"HYPRUSE_AUTH_GUARD": "<HYPRUSE_AUTH_GUARD>",
"HYPRUSE_STRICT": "<HYPRUSE_STRICT>"
}
}
}
}Replace <…> with your own values. 6 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from hypruse <command>
Platform CLI
gemini mcp add -e HYPRUSE_SCREENSHOT_MODE=<HYPRUSE_SCREENSHOT_MODE> -e HYPRUSE_READONLY=<HYPRUSE_READONLY> -e HYPRUSE_CONFINE=<HYPRUSE_CONFINE> -e HYPRUSE_AUTH_GUARD=<HYPRUSE_AUTH_GUARD> -e HYPRUSE_STRICT=<HYPRUSE_STRICT> hypruse uvx hypruseReplace <…> with your own values. 6 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from hypruse <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 hypruse
How do I install hypruse in Claude Code?
Run claude mcp add hypruse -- uvx hypruse.
What does hypruse do?
It gives an AI agent MCP tools to inspect a Hyprland desktop, capture screenshots and interact with windows.
What does hypruse need to work?
It requires Hyprland. Apps must expose an accessibility tree for ui to read their controls; marks needs ImageMagick to draw numbered labels.
