README.md
MCP server for Hyprland desktop automation and Wayland control.
hyprland-mcp
MCP server for Hyprland desktop automation. Gives AI assistants the ability to see the screen, control mouse and keyboard, manage windows, and interact with the desktop — all through Hyprland's native Wayland tools.
Built for Claude Code, but works with any MCP client.
What it does
- Screenshots — Capture the full desktop, a specific monitor, window, or region. Images are automatically resized and JPEG-compressed to fit within MCP output limits. Every screenshot includes a coordinate mapping so the AI knows how to translate image positions to screen coordinates.
- OCR — Find and click text on screen using Tesseract.
click_text("Send")captures a screenshot, runs OCR, finds the text, and clicks it — all in one tool call. Auto-scopes to the active window for better accuracy. - Mouse — Move, click, scroll, and drag. Positioning uses Hyprland's native
movecursor(pixel-accurate, no mouse acceleration issues). - Keyboard — Type text or send key combinations. Shortcuts can target specific windows without focusing them.
- Window management — List, focus, close, move, resize, fullscreen, and float windows.
- Workspaces & monitors — List workspaces, switch between them, query monitor layout and cursor position.
- Clipboard — Read and write clipboard text.
- App launching — Launch applications through Hyprland (detached, no shell expansion).
Requirements
- Hyprland (Wayland compositor)
- Python 3.10+
- System tools:
grim,wtype,ydotool,wl-clipboard,tesseract
The install script checks for all of these and offers to install any that are missing.
Installation
curl -sSL https://raw.githubusercontent.com/alderban107/hyprland-mcp/main/install.sh | bash
The install script handles everything automatically:
- Detects your package manager (pacman, apt, dnf, zypper, xbps, emerge, nix)
- Installs any missing system dependencies
- Installs hyprland-mcp via pipx
- Registers the MCP server with Claude Code
Restart Claude Code after installing.
Verify with claude mcp list — you should see hyprland: ✓ Connected.
Manual installation
pipx install git+https://github.com/alderban107/hyprland-mcp.git
claude mcp add --transport stdio --scope user hyprland -- hyprland-mcp
Or from a local clone:
git clone https://github.com/alderban107/hyprland-mcp.git
cd hyprland-mcp
python3 -m venv .venv
.venv/bin/pip install -e .
claude mcp add --transport stdio --scope user hyprland -- /path/to/hyprland-mcp/.venv/bin/hyprland-mcp
Tools (27)
Screenshot & OCR
| Tool | Description |
|---|---|
screenshot |
Capture desktop, monitor, window, or region. Returns inline JPEG + coordinate mapping for translating image positions to screen coordinates. |
screenshot_with_ocr |
Screenshot + OCR in one call. Returns the image and all detected text. Auto-scopes to active window. |
click_text |
Find text on screen via OCR and click it. One tool call replaces screenshot → parse → click. Auto-scopes to active window. |
find_text_on_screen |
Find text on screen via OCR. Returns screen coordinates of all matches, ready for mouse_click. |
type_into |
Find a text input field by placeholder text, click it, type, and optionally press Enter. |
Mouse
| Tool | Description |
|---|---|
mouse_move |
Move cursor to absolute coordinates (pixel-accurate via Hyprland's movecursor) |
mouse_click |
Click at position or current location (left/right/middle, single/double) |
mouse_scroll |
Scroll wheel up/down at position or current location |
mouse_drag |
Click-drag from one position to another |
Keyboard
| Tool | Description |
|---|---|
type_text |
Type text as keyboard input (via wtype) |
key_press |
Press a key combination like ctrl+c, alt+F4 (via Hyprland sendshortcut) |
send_shortcut |
Send a shortcut with explicit modifiers and key, optionally targeting a specific window |
Window Management
| Tool | Description |
|---|---|
list_windows |
List all windows with class, title, size, position (filterable by workspace/monitor) |
get_active_window |
Get details about the currently focused window |
focus_window |
Focus a window by class or title selector |
close_window |
Close a window (WM_CLOSE — apps can show save dialogs) |
move_window |
Move a window to a pixel position or workspace |
resize_window |
Resize a window to exact pixel dimensions |
toggle_fullscreen |
Toggle fullscreen or maximize mode |
toggle_floating |
Toggle floating mode |
Workspace & Monitor
| Tool | Description |
|---|---|
list_monitors |
List connected monitors with resolution, position, refresh rate |
list_workspaces |
List active workspaces with window counts |
| `switch_workspac |
Tools (7)
screenshotCapture desktop, monitor, window, or region with coordinate mapping.screenshot_with_ocrCapture screenshot and perform OCR in one call.click_textFind text on screen via OCR and click it.mouse_moveMove cursor to absolute coordinates.type_textType text as keyboard input.list_windowsList all windows with class, title, size, and position.focus_windowFocus a window by class or title selector.Configuration
claude_desktop_config.json
{"mcpServers": {"hyprland": {"command": "hyprland-mcp"}}}Try it
→Take a screenshot of the current window and tell me what text is visible.
→Find the 'Settings' button on my screen and click it.
→List all open windows and focus the one with 'Firefox' in the title.
→Type 'Hello World' into the active text field.
→Move the current window to the second workspace.