hyprland-mcp-server

MCP server (Model Context Protocol) for capturing screenshots and querying window/monitor/workspace state in the Hyprland Wayland compositor.

Enables LLMs to see your screen, inspect open windows, and navigate your desktop layout.

Requirements

Binary	Source
hyprctl	Bundled with Hyprland
grim	https://sr.ht/~emersion/grim/ (pacman -S grim / apt install grim)

The server must run inside an active Hyprland session with WAYLAND_DISPLAY set.

Installation

cd hyprland-mcp-server
npm install
npm run build

MCP Client Configuration

Claude Desktop / opencode

{
  "mcpServers": {
    "hyprland": {
      "command": "node",
      "args": ["/absolute/path/to/hyprland-mcp-server/dist/index.js"]
    }
  }
}

Run manually (for testing)

node dist/index.js
# or during development:
npm run dev

Tools

Tool	Description
hyprland_list_windows	List all open windows with class, title, address, geometry, workspace
hyprland_get_active_window	Get metadata for the currently focused window
hyprland_screenshot_window	Capture a PNG of a specific window (by address, class, title, or PID)
hyprland_screenshot_active_window	Capture a PNG of the currently focused window
hyprland_screenshot_monitor	Capture a full monitor screenshot
hyprland_list_monitors	List monitors with resolution, refresh rate, position, scale
hyprland_list_workspaces	List workspaces with window counts and monitor assignments
hyprland_click_at	Simulates a mouse click at absolute global coordinates in Hyprland. Useful for programmatically interacting with specific screen positions.
hyprland_click_window	Targets the center of a specific window in Hyprland for a mouse click, with optional offsets.
hyprland_click_window_relative	Clicks inside a selected window using window-local coordinates (local_x,local_y) with optional bounds validation.
hyprland_click_and_screenshot_active	Performs click with optional bounded retries and returns active-window screenshot for immediate verification.
hyprland_move_cursor	Moves the mouse cursor to specified global coordinates without clicking.
hyprland_get_cursor_pos	Retrieves the current cursor position in the global layout coordinates.
hyprland_type_text	Types a text string into the currently focused window using Wayland-native input injection.
hyprland_press_key	Sends a single keypress event (e.g., Enter, Tab, Escape) to the currently focused window.
hyprland_send_key	Sends a key or a key combination (e.g., "Ctrl+C") to a specific window or the active window.
hyprland_focus_window	Brings keyboard and compositor focus to a specific window, enabling further interactions.

Example Usage

"Screenshot the terminal window"
  -> hyprland_screenshot_window(class="Alacritty")

"What apps are open on workspace 2?"
  -> hyprland_list_windows(workspace_id=2)

"Take a screenshot of my screen"
  -> hyprland_screenshot_monitor()

"What am I looking at right now?"
  -> hyprland_get_active_window()

Screenshot Response

Screenshot tools return:

• A text block with geometry, file path, and window info
• An image block (base64 PNG) so the LLM can visually inspect the content
• A structuredContent block with JSON metadata

Screenshots are saved to a temporary directory under /tmp/hyprland-mcp-*.

Click Precision Notes

• hyprland_click_at expects global monitor coordinates.
• hyprland_screenshot_window is naturally read as window-local pixels.
• Convert local → global when needed:

global_x = window_x + local_x
global_y = window_y + local_y

To avoid coordinate-space mistakes, prefer:

1. hyprland_click_window_relative when targeting UI points from a window screenshot.
2. hyprland_click_window when clicking near window center with offsets.
3. hyprland_click_and_screenshot_active when you want click+verify loop in one call.

Development

npm run dev      # tsx watch mode
npm run build    # compile TypeScript
npm run clean    # remove dist/

Architecture

src/
  index.ts              # Server init, dependency check, tool registration
  types.ts              # TypeScript interfaces for Hyprland IPC structs
  schemas/index.ts      # Shared Zod schemas (ResponseFormat, WindowSelector)
  services/
    hyprland.ts         # hyprctl wrapper, grim capture, window/monitor queries
  tools/
    list-windows.ts
    get-active-window.ts
    screenshot-window.ts
    screenshot-active-window.ts
    screenshot-monitor.ts
    list-monitors.ts
    list-workspaces.ts