Provides tools for interacting with the Hyprland Wayland compositor, enabling screen capture, window management, and desktop manipulation.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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.
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.
Binary | Source |
| Bundled with Hyprland |
| https://sr.ht/~emersion/grim/ ( |
The server must run inside an active Hyprland session with WAYLAND_DISPLAY set.
Related MCP server: kwin-mcp
cd hyprland-mcp-server
npm install
npm run build{
"mcpServers": {
"hyprland": {
"command": "node",
"args": ["/absolute/path/to/hyprland-mcp-server/dist/index.js"]
}
}
}node dist/index.js
# or during development:
npm run devTool | Description |
| List all open windows with class, title, address, geometry, workspace |
| Get metadata for the currently focused window |
| Capture a PNG of a specific window (by address, class, title, or PID) |
| Capture a PNG of the currently focused window |
| Capture a full monitor screenshot |
| List monitors with resolution, refresh rate, position, scale |
| List workspaces with window counts and monitor assignments |
| Simulates a mouse click at absolute global coordinates in Hyprland. Useful for programmatically interacting with specific screen positions. |
| Targets the center of a specific window in Hyprland for a mouse click, with optional offsets. |
| Clicks inside a selected window using window-local coordinates ( |
| Performs click with optional bounded retries and returns active-window screenshot for immediate verification. |
| Moves the mouse cursor to specified global coordinates without clicking. |
| Retrieves the current cursor position in the global layout coordinates. |
| Types a text string into the currently focused window using Wayland-native input injection. |
| Sends a single keypress event (e.g., Enter, Tab, Escape) to the currently focused window. |
| Sends a key or a key combination (e.g., "Ctrl+C") to a specific window or the active window. |
| Brings keyboard and compositor focus to a specific window, enabling further interactions. |
"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 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-*.
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_yTo 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.
npm run dev # tsx watch mode
npm run build # compile TypeScript
npm run clean # remove dist/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.tsThis server cannot be installed
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Provides cloud browser automation capabilities using Stagehand and Browserbase, enabling LLMs to i…
Eyes and hands on real Windows PCs — observe, click, type via Glasswarp API.
Generate images, GIFs, and PDFs from HTML, URLs, or templates — from your AI agent.
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