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 "Install 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 Related Servers Score Discussions

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: kwin-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 installed

license - not found

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/rodsilvavieira2/hyprland-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server