Which integrations are available for this server?

Provides tools for interacting with the Hyprland Wayland compositor, enabling screen capture, window management, and desktop manipulation.

How do I use hyprland-mcp-server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@hyprland-mcp-server take a screenshot of my screen" 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.

hyprland-mcp-server

by rodsilvavieira2

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

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.

Related MCP server: screen-mcp

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:

hyprland_click_window_relative when targeting UI points from a window screenshot.
hyprland_click_window when clicking near window center with offsets.
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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

SentinelX MCPOAuth
app.sentinelx
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Shell Access OS Automation
28
browserbasehq-mcp-browserbaseOAuth
ai.smithery
Provides cloud browser automation capabilities using Stagehand and Browserbase, enabling LLMs to i…
Browser Automation Web Scraping Agent Orchestration
23,407
Hyperbrowser
io.github.pipeworx-io
Hyperbrowser MCP — wraps the Hyperbrowser AI-agent browsing API
Browser Automation Agent Orchestration
1
Glasswarp A
com.glasswarp
Eyes and hands on real Windows PCs — observe, click, type via Glasswarp API.
OS Automation Autonomous Agents
162

Related MCP Servers

hyprland-mcp
OS Automation App Automation
Keylessboi
F
license
Not graded
quality
B
maintenance
Enables AI agents to control a Hyprland Wayland desktop by listing windows, capturing screenshots, and sending input to a dedicated agent workspace without disrupting the user's screen.
Updated a month ago (2026-08-14 22:52 UTC)
-
screen-mcp
Image & Video Processing AI & Machine Learning
ferre-z
F
license
A
quality
C
maintenance
Gives AI agents eyes on Hyprland Wayland desktops by capturing screenshots via grim and offering optional image analysis with Gemini API.
Updated a month ago (2026-08-22 17:07 UTC)
6
-
desktop-mcp
Agent Orchestration Testing & QA Tools
Zetakai
A
license
A
quality
C
maintenance
Enables LLMs to capture desktop screenshots and control the mouse and keyboard on Linux, including Wayland, through MCP.
Updated a month ago (2026-08-21 19:59 UTC)
11
MIT
eyes-mcp
Image & Video Processing Testing & QA Tools Autonomous Agents
Rixmerz
F
license
A
quality
B
maintenance
Provides agents with temporary visual capture of Hyprland/Wayland monitors, windows, or regions as PNGs, enabling visual verification and self-correction of UI and desktop tasks.
Updated 21 days ago (2026-08-29 14:53 UTC)
8
-

hyprland-mcp-server

Requirements

Installation

MCP Client Configuration

Claude Desktop / opencode

Run manually (for testing)

Tools

Example Usage

Screenshot Response

Click Precision Notes

Development

Architecture

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

hyprland-mcp

screen-mcp

desktop-mcp

eyes-mcp