Hyprland 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

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

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