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: astra-linux-agent

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

Related MCP Connectors

BrowserHereOAuth
app.1ts.browserhere
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Browser Automation Agent Orchestration
1
https://browserhere.1ts.app/mcp
SentinelX MCPOAuth
app.sentinelx
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Shell Access OS Automation
216
https://mcp.sentinelx.app/mcp/mcp
ZionDeskOAuth
app.ziondesk
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
File Systems Command Line Browser Automation
1
https://mcp.ziondesk.app/mcp
BCD — Bridge Control Delegate A
com.snack-wrap.bcd
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
File Systems Command Line Browser Automation
751
https://bcd.snack-wrap.com/mcp

Related MCP Servers

hyprland-mcp
OS Automation App Automation
Keylessboi
A
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-09-20 22:38 UTC)
1
MIT
astra-linux-agent
OS Automation Shell Access Autonomous Agents
novique-ai
A
license
Not graded
quality
D
maintenance
Enables an AI agent to see and control a Linux desktop via Wayland/Hyprland, providing screenshots, structured desktop state, pointer/keyboard input, semantic window/workspace tools, and a policy engine for safe execution.
Updated 2 months ago (2026-09-07 00:43 UTC)
Apache 2.0
hypr-mcp
OS Automation Image & Video Processing
tuan-cre
A
license
B
quality
B
maintenance
Enables AI assistants to automate Hyprland desktop environments through screenshots, mouse/keyboard input, window management, workspaces, clipboard, app launching, and OCR.
Updated 2 months ago (2026-09-10 06:37 UTC)
27
1
MIT
Omarchy Computer MCP
OS Automation Autonomous Agents
Marlos001
A
license
Not graded
quality
B
maintenance
Enables MCP clients to inspect and control an Omarchy/Hyprland desktop by taking screenshots, focusing windows, moving/clicking the mouse, scrolling, typing text, and sending keyboard shortcuts.
Updated 2 months ago (2026-09-13 19:22 UTC)
MIT

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

astra-linux-agent

hypr-mcp

Omarchy Computer MCP