Provides desktop automation for Hyprland, including screenshots, OCR, mouse and keyboard input, window and workspace management, clipboard access, and app launching.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@hypr-mcp screenshot my current desktop and describe what you see"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Let MCP clients drive Hyprland: screenshots, mouse, keyboard, windows, workspaces, clipboard, launching apps, OCR.
Needs Hyprland 0.55 or newer. Older versions get a clear error instead of weird behavior. Made for OpenCode; anything else speaking MCP might work but hasn't been tested.
Hyprland, Python 3.10+, pipx, plus (Arch names, adapt to your distro):
Tool | For |
| screenshots, OCR |
| clicking, scroll, drag |
| typing, single keys |
| clipboard, pasting |
| finding text on screen |
No wtype? paste_text (clipboard + ctrl+v) covers most typing.
No tesseract? Models with vision just look at screenshots directly.
Related MCP server: hyprland-mcp-server
curl -sSL https://raw.githubusercontent.com/tuan-cre/hypr-mcp/main/install.sh | bashThat handles system deps and pipx install.
Then add to ~/.config/opencode/opencode.jsonc:
{
"mcp": {
"servers": {
"hypr": {
"type": "local",
"command": ["hypr-mcp"],
},
},
},
}Or manually: pipx install git+https://github.com/tuan-cre/hypr-mcp.git
Seeing — screenshot (inline JPEG + mapping, or path for full-res PNG
to disk), find_text_on_screen, click_text, wait_text.
Mouse — mouse_move, mouse_click, mouse_scroll, mouse_drag.
Keyboard — type_text, key_press, paste_text.
Windows — list_windows ([focused]/[floating] flags), focus_window,
close_window, move_window, resize_window, toggle_fullscreen,
toggle_floating.
Workspaces — list_workspaces ([focused] flag), switch_workspace,
toggle_special (move via move_window + "special:name").
Misc — list_monitors, get_cursor_position, clipboard_read,
clipboard_write, launch_app, wait_window.
Actions confirm themselves where possible (launch/focus/close wait for the
real event, not a sleep). No force-kill, no shell in launch_app,
clipboard reads are capped.
Env vars, all optional: HYPR_MCP_MAX_WIDTH (1440),
HYPR_MCP_JPEG_QUALITY (75), HYPR_MCP_OCR_MIN_CONF (30),
HYPR_MCP_EVENT_TIMEOUT (10s), HYPR_MCP_LAUNCH_TIMEOUT (30s).
MIT
OCR-find text and click it. Focusing window first if given.
Inputs: target (required), scope, button, double, +4 more. Returns: result
Read clipboard text (truncated to max_chars).
Inputs: max_chars. Returns: result
Write text to clipboard.
Inputs: text (required). Returns: result
Close a window (WM_CLOSE, apps may prompt to save).
Inputs: target. Returns: result
OCR-search for text. Returns absolute coords for mouse_click.
Inputs: target (required), scope, region, window, +1 more. Returns: result
Focus a window by selector ("class:firefox", "title:Doc", "address:0x...").
Inputs: target (required). Returns: result
Cursor position in absolute layout coordinates.
Inputs: no named parameters. Returns: result
Press combo ("ctrl+c") or single key ("Return"). Single source for shortcuts.
Inputs: keys (required), target. Returns: result
Launch an app detached (no shell — binary + args only). Waits for its window.
Slow starters (Steam) need the generous default; pass a smaller timeout for known-fast apps, larger for known-slow ones.
Inputs: command (required), timeout. Returns: result
List monitors with resolution, position, active workspace.
Inputs: no named parameters. Returns: result
List windows with class, title, size, position.
Inputs: monitor, workspace. Returns: result
List workspaces with window counts. Active one is marked [focused].
Inputs: no named parameters. Returns: result
Click at coords or current pos. window focuses first (coords stay absolute).
Inputs: x, y, button, double, +1 more. Returns: result
Drag in absolute coordinates.
Inputs: end_x (required), end_y (required), start_x (required), start_y (required), +1 more. Returns: result
Move cursor to absolute coordinates (pixel-accurate).
Inputs: x (required), y (required). Returns: result
Scroll wheel, optionally after moving to absolute coords.
Inputs: x, y, amount, direction. Returns: result
Move active/selected window to pixels and/or workspace (incl. "special:name").
Inputs: x, y, target, workspace. Returns: result
Reliable path for unicode/long text: clipboard + ctrl+v (wtype chokes on these).
Inputs: text (required), target. Returns: result
Resize active/selected window to pixel dimensions.
Inputs: width (required), height (required), target. Returns: result
Screenshot to inline JPEG + coordinate mapping (coords are absolute).
Pass path to save full-res PNG to disk instead (no token cost) — for debugging OCR without an inline image.
Inputs: path, region, window, monitor, +3 more.
Switch to a workspace by name/number (e.g. "1", "special:scratchpad").
Inputs: workspace (required). Returns: result
Set floating state. action: "set"|"unset"|"toggle".
Inputs: action, target. Returns: result
Set fullscreen state. mode: "fullscreen"|"maximize", action: "set"|"unset"|"toggle".
Inputs: mode, action. Returns: result
Toggle a special (scratchpad) workspace by name.
Inputs: name (required). Returns: result
Type text via wtype.
Inputs: text (required), delay_ms. Returns: result
Wait for on-screen text to appear (or disappear). Replaces blind sleeps.
Use for in-window state no compositor event covers: button flips (UPDATE→PLAY), page content, dialogs. Returns instantly on match.
Inputs: target (required), region, window, monitor, +2 more. Returns: result
Wait for a window to exist / reach a title. Replaces blind sleeps.
Use after launch_app or navigation: title change is the load signal (e.g. title_contains="Example Domain"). Returns instantly on match.
Inputs: target, timeout, title_contains. Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Scored across 27 tools
Each tool targets a distinct resource or action. Overlapping categories (type_text, key_press, paste_text) are clearly differentiated by use case, and OCR tools (find_text_on_screen, wait_text, click_text) have precise roles. No ambiguity that would cause an agent to select the wrong tool.
All tools follow a consistent snake_case verb_noun pattern (list_monitors, switch_workspace, mouse_click, clipboard_write). The verbs are predictable and the naming is uniform, making the set highly readable and navigable.
With 27 tools, the count exceeds the 25+ threshold for 'too many'. While the domain is broad (window management, input, OCR, clipboard), the tool surface feels heavy and could potentially be consolidated. The scope justifies many tools, but the sheer number edges into over-provisioning.
The toolset covers window lifecycle, workspace switching, input control, OCR, clipboard, and screenshots. Minor gaps exist (e.g., no minimize or workspace creation), but core automation workflows are fully supported, and agents can accomplish most tasks without dead ends.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
A cloud Linux desktop for your AI: browse, click, type, read the screen and run commands.
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.