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:

1. Detects your package manager (pacman, apt, dnf, zypper, xbps, emerge, nix)

2. Installs any missing system dependencies

3. Installs hyprland-mcp via pipx

4. Registers the MCP server with Claude Code

Restart Claude Code after installing.

Verify with claude mcp list — you should see hyprland: ✓ Connected.

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

Mouse

Keyboard

Window Management

Workspace & Monitor

Clipboard & System

How it works

Screenshot coordinate mapping

Multi-monitor setups and image scaling make coordinate translation tricky. Every screenshot call returns a coordinate mapping alongside the image:

Coordinate mapping: This 941x1030 image covers screen region
starting at absolute (5447, 38), native size 941x1030.
To convert image coordinates to absolute screen coordinates:
  screen_x = image_x * 1.00 + 5447
  screen_y = image_y * 1.00 + 38

This prevents the AI from using image pixel positions directly as screen coordinates — a common failure mode on multi-monitor setups where monitors have different positions in the layout.

OCR and dark themes

Tesseract OCR was designed for black text on white paper. Most desktop apps use dark themes, which tanks OCR accuracy. hyprland-mcp automatically detects dark-background screenshots and inverts them before running OCR, significantly improving text detection.

OCR tools auto-scope to the active window by default (configurable with scope="full" for the entire desktop). Smaller capture area = better OCR accuracy = more reliable coordinate mapping.

Mouse positioning

Mouse movement uses hyprctl dispatch movecursor — Hyprland's native IPC command that sets the cursor to exact pixel coordinates. No mouse acceleration, no relative movement, no coordinate drift. ydotool is only used for click and scroll events (which don't involve positioning).

Screenshot sizing

Screenshots are automatically scaled to fit within MCP output limits. Default: max width 1024px, JPEG quality 60. A 2560x1440 desktop becomes ~80-100KB — small enough for inline display in the conversation.

For reading fine text or UI details, use the region parameter to capture a smaller area at full resolution, or capture a specific window.

Project structure

hyprland_mcp/
  server.py       # FastMCP instance, all tool definitions, entry point
  hyprctl.py      # Async wrappers for hyprctl IPC (query, dispatch, batch)
  screenshot.py   # grim capture + Pillow resize/compress + coordinate mapping
  input.py        # Mouse (movecursor + ydotool) and keyboard (wtype + sendshortcut)
  clipboard.py    # wl-copy / wl-paste wrappers
  ocr.py          # Tesseract OCR with dark-theme preprocessing
  errors.py       # Exception hierarchy + tool availability checks

Safety

• close_window sends WM_CLOSE — apps can show "save changes?" dialogs. There is no force-kill tool.

• launch_app goes through hyprctl dispatch exec — detached from the MCP process, no shell expansion.

• No file system access — the MCP can see the screen and interact with it, but cannot read or write files.

• Missing system tools produce clear error messages listing what to install.

License

MIT