hyprland-mcp
This server provides an MCP interface to control the Hyprland Wayland compositor via Claude, enabling full window manager automation and configuration.
Window Management: List, get active, focus, close, kill, move to workspace, resize, toggle floating/fullscreen, and pin windows.
Workspace Management: List, get active, switch, move to monitor, rename, and toggle special/scratchpad workspaces.
Monitor Control: List, focus, and configure monitor settings (resolution, position, scale, enable/disable).
System Configuration: Get/set Hyprland config options at runtime, reload the config file, get version info, and list all keybindings.
Screenshots: Capture the full screen, a specific monitor, an interactively selected region, or the active window.
Notifications: Send desktop notifications and dismiss Hyprland's built-in on-screen notifications.
App Launcher: Toggle hyprlauncher open/closed and pre-warm its daemon for instant launches.
Window Grouping: Create/ungroup tabbed containers, cycle through windows in a group, and lock/unlock groups.
Window Tagging: Add, remove, or toggle tags on windows for grouping and rule matching.
Cursor Control: Move the cursor to absolute screen coordinates or to a specific corner of a window.
Blue-Light Filter (hyprsunset): Set color temperature, adjust gamma, disable the filter, reset to scheduled profile, and view the active profile.
Wallpaper (hyprpaper): Set wallpapers per-monitor or as a global fallback, and list currently active wallpapers.
Escape Hatches: Use hyprland_dispatch to call any Hyprland dispatcher or hyprctl_raw to execute any raw hyprctl subcommand for operations not covered by dedicated tools.
Allows AI agents (like Claude) to control the Hyprland window manager, including managing windows, workspaces, monitors, keybinds, notifications, screenshots, app launcher, tags, groups, cursor, blue light filter, and wallpaper.
Click on "Deploy 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 Switch to workspace 3"
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
An MCP server that lets Claude control Hyprland through hyprctl.
Talks to Hyprland over its IPC socket via hyprctl/hyprctl -j, and shells out to
grim/slurp/notify-send for screenshots and notifications. Runs over stdio, so
it only works when launched inside your Hyprland session (or with
HYPRLAND_INSTANCE_SIGNATURE forwarded to it).
Tools
Windows:
list_windows,get_active_window,focus_window,close_window,kill_active_window,kill_window,send_window_signal,move_window_to_workspace,move_active_window,resize_active_window,toggle_floating,toggle_pseudo_tiled,toggle_fullscreen,set_fullscreen_state,pin_window,bring_window_to_top,center_window,cycle_next_window,swap_window,alter_z_order,toggle_swallowWorkspaces:
list_workspaces,get_active_workspace,switch_workspace,move_workspace_to_monitor,rename_workspace,toggle_special_workspace,change_workspace_id,swap_monitor_workspacesMonitors:
list_monitors,focus_monitor,set_monitor_configConfig:
get_config_option,set_config_option,reload_hyprland_config,get_hyprland_versionKeybinds:
list_keybindsNotifications:
send_notification,dismiss_notificationsScreenshots:
take_screenshot,take_region_screenshot(interactive, via slurp),screenshot_active_windowApp launcher:
toggle_launcher,prewarm_launcher_daemon(controls hyprlauncher, Hyprland's first-party app picker — a self-toggling daemon, not a hyprctl dispatcher)Tags:
tag_window,clear_window_tagsGroups (tabbed containers):
toggle_group,group_cycle,toggle_group_lock,deny_window_from_group,group_active_window,move_window_in_groupCursor:
move_cursor,move_cursor_to_corner,focus_directionSystem:
set_submap,exec_raw,exec_cmd,toggle_dpms,layout_message,list_instances,exit_hyprlandhyprsunset (blue light filter):
set_sunset_temperature,disable_sunset_filter,set_sunset_gamma,reset_sunset,get_sunset_profilehyprpaper (wallpaper):
set_wallpaper,list_active_wallpapershypridle (idle management):
start_hypridle,stop_hypridle,get_hypridle_statushyprlock (screen lock):
lock_screen,unlock_screen,refresh_lockscreen,get_lock_status,clear_crashed_lockscreenhyprpicker (color picker):
pick_colorEscape hatches:
hyprland_dispatch(anyhyprctl dispatch <dispatcher>),hyprctl_raw(any rawhyprctlsubcommand)
Related MCP server: device-controller-mcp
Requirements
Node.js 18+
Hyprland (obviously) with
hyprctlonPATHOptional:
grim+slurpfor screenshots,notify-send(mako/dunst/similar) for notifications,hyprlauncherfor the app launcher tools,hyprsunsetfor blue-light filter tools,hyprpaper(withipc = true, the default, inhyprpaper.conf) for wallpaper tools,hypridle/hyprlockfor idle/lock tools,hyprpicker(+wl-clipboardfor its autocopy option) for the color picker tool,pgrep/pkill(procps/procps-ng, virtually always preinstalled) for the hypridle/hyprlock and hyprlauncher tools — these all degrade gracefully or error clearly if missing
Build
npm install
npm run buildThis produces build/index.js.
Wire it up
Claude Code
claude mcp add hyprland -- node /absolute/path/to/hyprland-mcp/build/index.jsClaude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"hyprland": {
"command": "node",
"args": ["/absolute/path/to/hyprland-mcp/build/index.js"]
}
}
}Claude Desktop on Linux is launched by your session, so HYPRLAND_INSTANCE_SIGNATURE
should already be in its environment. If you ever run this from a context that doesn't
have it (e.g. a systemd unit, SSH session, or this same tool running Claude Code from
inside a sandbox), export it first, e.g.:
export HYPRLAND_INSTANCE_SIGNATURE=$(ls /tmp/hypr | head -n1)Testing
src/dispatch-expressions.ts holds pure, side-effect-free builders for every Lua
expression this project sends to hyprctl dispatch — no hyprctl/child_process
calls, so they're unit-testable without a real Hyprland session:
npm testThis runs tsc then Node's built-in test runner over
src/__tests__/dispatch-expressions.test.ts, asserting the exact string each
builder produces — including the two verbatim wiki examples (window.tag with a
target, workspace.toggle_special's bare-string argument). This is what actually
catches syntax drift: when a future Hyprland release changes an hl.dsp.* shape,
update the builder and its test together rather than only touching the call site
buried inside a tool handler.
It already caught one real bug during development: denyWindowFromGroupExpr()
with no target was emitting hl.dsp.window.deny_from_group({ }) (an empty table)
instead of a clean (), because the builder always passed an args object even when
every key in it was undefined. Worth knowing if you add a new builder where a
target/selector is the only possible key — luaCall() in src/hyprctl.ts now
auto-detects all-undefined objects and collapses them to a bare path() call,
but it's still good practice to build the whole args object conditionally for
non-obvious cases. A similar luaCall improvement (auto-collapsing empty tables to
bare ()) also fixed the same edge case for clearWindowTagsExpr, bringWindowToTopExpr,
centerWindowExpr, cycleNextWindowExpr, and moveGroupWindowExpr when called
without targets.
Security note: unlock_screen
hyprlock has no password-aware IPC — its only documented unlock mechanism is
SIGUSR1 (pkill -USR1 hyprlock), which this project's unlock_screen tool uses
directly. That means it bypasses PAM/password authentication entirely: anything
able to invoke this MCP tool can unlock a locked session without knowing the
password. This isn't a bug or an oversight, it's the only unlock mechanism hyprlock
exposes — but it does mean access to this MCP server should be treated as
equivalent in sensitivity to your screen lock's own security boundary. Don't wire
this server up somewhere a lock screen is meant to be a real barrier (e.g. a
shared/untrusted machine) without accounting for that.
Design notes
hyprsunsetandhyprpaperare controlled through their ownhyprctl <name> <args>subcommand families (hyprctl hyprsunset ...,hyprctl hyprpaper ...) — likekeyword/getoption, these are untouched by the 0.55 Lua dispatch rewrite, sosrc/tools/hyprsunset.tsandhyprpaper.tscallrunHyprctl()directly with no Lua expression involved.All
hyprctlcalls go throughexecFile(never a shell), so arguments can never be used for shell injection.Read commands (
list_*,get_*) always go throughhyprctl -jand get parsed as JSON so Claude gets structured data, not text to eyeball.Every dedicated tool is a thin wrapper around a specific dispatcher/subcommand.
hyprland_dispatchandhyprctl_rawexist as escape hatches for anything not yet wrapped (Hyprland adds dispatchers between releases) — checkhyprctl dispatch --helpor the Hyprland wiki for the full list.Screenshot tools write to a temp dir, base64-encode, and clean up after themselves.
Move/resize tools use Hyprland's
exact/relative dispatcher argument conventions (moveactive,resizeactive) rather than reimplementing geometry math.
Extending
Add a new file under src/tools/, export a register*Tools(server) function, and
call it from src/index.ts. Keep one hyprctl concern (e.g. layers, devices,
pin/special-workspaces) per file so the project stays easy to navigate.
Available Tools
48 toolsclose_windowA
Close a window by address or selector. Sends the same signal as clicking the close button (not force-kill).
Inputs: target (required).
deny_window_from_groupB
Prevent a window from being added to a group, or from becoming a group itself. NOTE: this is documented as existing ('the window.deny_from_group dispatcher') but its Lua path is a best-effort guess (hl.dsp.window.deny_from_group) by analogy with the other window.* dispatchers — not directly confirmed. Verify before relying on it.
Inputs: target.
disable_sunset_filterA
Disable hyprsunset's blue-light filter entirely, returning color temperature to normal (hyprctl hyprsunset identity). Temporary — reverts at the next scheduled profile.
Inputs: no named parameters.
dismiss_notificationsB
Dismiss all currently visible Hyprland built-in on-screen notifications. UNVERIFIABLE as of this writing: send_notification's fallback was confirmed to produce no visible notification in the first place, so there was nothing on a real session to confirm this actually clears. The underlying call (hl.notification.get() + :dismiss() per handle) runs without erroring, but that's equally consistent with 'it worked' and 'it iterated over nothing'. Given send_notification's fallback is effectively non-functional right now, this tool likely has nothing to do in practice either.
Inputs: no named parameters.
focus_monitorA
Move focus to a given monitor. NOTE: unlike window/workspace dispatchers, the 0.55+ Lua path for monitor focus isn't documented anywhere confirmable at authoring time — this guesses hl.dsp.focus() (the same top-level dispatcher used for window focus) also accepts a monitor key. If it errors, use hyprland_dispatch with a raw_expression checked against your Lua LSP stubs instead.
Inputs: monitor (required).
focus_windowA
Focus a window by its unique address (from list_windows) or by class/title regex selector (e.g. 'class:^(firefox)$').
Inputs: target (required).
get_active_windowB
Get the currently focused/active window.
Inputs: no named parameters.
get_active_workspaceA
Get the currently active workspace on the focused monitor.
Inputs: no named parameters.
get_config_optionA
Read the current value of a Hyprland config option, e.g. 'general:gaps_in' or 'decoration:rounding'.
Inputs: option (required).
get_hyprland_versionA
Get the running Hyprland version, commit, and build flags.
Inputs: no named parameters.
get_sunset_profileA
Print hyprsunset's currently active time-based profile. NOTE: the same forum bug report affecting reset_sunset also reported this command as broken on hyprsunset v0.3.3 — if it errors, that's a known upstream issue, not a wiring problem here.
Inputs: no named parameters.
group_cycleA
Cycle to the next or previous window within the active group. Confirmed: hl.dsp.group.next() and hl.dsp.group.prev().
Inputs: direction (required).
hyprctl_rawA
Escape hatch: run any raw hyprctl subcommand that ISN'T 'dispatch' — e.g. 'reload', 'version', 'splash', 'layers', 'devices', 'systeminfo'. These take plain argv, not Lua expressions (only 'dispatch' changed syntax in 0.55). Pass '-j' yourself as the first arg if you want JSON output.
Inputs: args (required).
hyprland_dispatchA
Escape hatch: run any Hyprland dispatcher not covered by a dedicated tool. As of Hyprland 0.55, hyprctl dispatch takes a single Lua expression that must evaluate to a dispatcher table built from the hl.dsp.* namespace (e.g. hl.dsp.window.tag, hl.dsp.group.toggle, hl.dsp.submap, hl.dsp.cursor.move, hl.dsp.exec_cmd) — it is NOT the old hyprctl dispatch <name> <args> positional form, which will error under 0.55+. Give EITHER (path + args) to have this tool build the call for you, OR raw_expression for anything with unusual shape (e.g. a dispatcher taking a bare string/number instead of a table, like hl.dsp.exec_cmd('firefox') or hl.dsp.submap("reset")). Check https://wiki.hypr.land/Configuring/Basics/Dispatchers/ or your Lua LSP stubs for the current dispatcher list and signatures if unsure.
Inputs: args, path, raw_expression.
kill_active_windowA
Force-kill the currently focused window (hl.dsp.window.kill(), the 0.55+ equivalent of the old killactive dispatcher).
Inputs: no named parameters.
list_active_wallpapersA
List the currently active wallpaper path for each monitor.
Inputs: no named parameters.
list_keybindsA
List all configured keybindings, including modmask, key, dispatcher, and argument.
Inputs: no named parameters.
list_monitorsA
List all connected monitors with resolution, position, scale, refresh rate, and active workspace.
Inputs: no named parameters.
list_windowsA
List all open windows (clients) with their address, class, title, workspace, position, size, and floating/fullscreen state.
Inputs: no named parameters.
list_workspacesA
List all workspaces across all monitors, including window counts and last-focused window.
Inputs: no named parameters.
move_active_windowC
Move the active window by a pixel delta, or to an absolute position.
Inputs: x (required), y (required), mode (required).
move_cursorB
Move the cursor to absolute screen coordinates. Confirmed: hl.dsp.cursor.move({ x, y }).
Inputs: x (required), y (required).
move_cursor_to_cornerB
Move the cursor to one of a window's four corners. Confirmed: hl.dsp.cursor.move_to_corner({ corner, window? }).
Inputs: corner (required), target.
move_window_to_workspaceB
Move a window to a different workspace.
Inputs: workspace (required), silent, target.
move_workspace_to_monitorB
Move an entire workspace (and all its windows) to a different monitor.
Inputs: monitor (required), workspace (required).
pin_windowA
Pin the active window so it stays visible across all workspaces. Only works on FLOATING windows — Hyprland rejects pinning a tiled window with a 'Window does not qualify to be pinned' warning (not an error; the call succeeds but has no effect). Use toggle_floating first if this warns and the window should stay pinned.
Inputs: no named parameters.
prewarm_launcher_daemonA
Start the hyprlauncher daemon in the background WITHOUT opening its window (hyprlauncher -d). Useful once at session start so the first real toggle_launcher call is instant rather than paying daemon-startup cost. Safe to call even if the daemon is already running.
Inputs: no named parameters.
reload_hyprland_configA
Reload hyprland.conf (equivalent to 'hyprctl reload').
Inputs: no named parameters.
rename_workspaceC
Rename a workspace by id.
Inputs: name (required), workspace (required).
reset_sunsetA
Reset hyprsunset override(s) back to whatever the current time-based profile specifies. NOTE: a Hyprland forum bug report (hyprsunset v0.3.3) found this specific command returns 'invalid command' while temperature/identity/gamma work fine — if you hit that, there's no clean workaround short of manually calling set_sunset_temperature/set_sunset_gamma/disable_sunset_filter with the values your profile should have at the current time.
Inputs: target.
resize_active_windowA
Resize the active window by a pixel delta, or to an exact size.
Inputs: mode (required), width (required), height (required).
screenshot_active_windowA
Screenshot just the currently focused window, cropped via grim -g using the window's box from hyprctl activewindow.
Inputs: no named parameters.
send_notificationA
Send a desktop notification via notify-send (requires a notification daemon like mako or dunst running). If notify-send is unavailable, falls back to Hyprland's built-in hl.notification.create — but a real-session test confirmed this fallback produces NO VISIBLE notification even though the underlying call succeeds without error (likely a Hyprland 0.55.4 rendering gap, not a bug in this call). Practically: if notify-send isn't installed, treat this tool as non-functional and tell the user to install a real notification daemon rather than assuming the fallback message means something appeared.
Inputs: title (required), body, icon, urgency, +2 more.
set_config_optionA
Set a Hyprland config option at runtime via 'hyprctl keyword'. This does NOT persist to hyprland.conf — it's a live, in-memory override until reload. Good for experimenting before writing the value into the actual config file.
Inputs: value (required), option (required).
set_monitor_configA
Apply a monitor config via 'hyprctl keyword monitor', same syntax as hyprland.conf's monitor= line. Useful for resolution/position/scale/enable-disable changes. Unlike 'dispatch', 'keyword' is a config-value setter rather than the dispatch mechanism that changed in 0.55, so this should be unaffected — but if it errors on your version, the Lua equivalent is likely hl.config({ monitor = { ... } }), which isn't reachable through this tool's escape hatches (they're dispatch-only) and would need a small code change.
Inputs: config (required).
set_sunset_gammaA
Set or adjust hyprsunset's gamma (perceived brightness). Absolute percent (e.g. '50' = 50%) or a relative delta with an explicit sign (e.g. '+10', '-10'). Max is 150% by default, raisable via max-gamma in hyprsunset.conf, hard-capped at 200%. Using gamma for brightness degrades color accuracy — prefer real monitor brightness control (DDC/backlight) if available.
Inputs: value (required).
set_sunset_temperatureA
Set hyprsunset's color temperature in Kelvin (lower = warmer/more orange, e.g. 2500-4000 for a strong blue-light filter; higher, e.g. 6500, is closer to neutral daylight). This override is temporary and will be replaced once hyprsunset's next scheduled profile activates.
Inputs: kelvin (required).
set_wallpaperA
Set the wallpaper for a monitor (or the fallback for all monitors that don't have one specifically assigned, if monitor is omitted). Loads the image on demand — no separate preload step needed on current hyprpaper versions.
Inputs: path (required), monitor, fit_mode.
switch_workspaceA
Switch the focused monitor to a given workspace.
Inputs: workspace (required).
tag_windowA
Add, remove, or toggle a static tag on a window. Tags are used for grouping windows and can be matched in window rules (e.g. hl.window_rule({ match = { tag = 'code' }, ... })). Confirmed syntax: hl.dsp.window.tag({ tag = '+code' }) adds, '-code' removes, 'code' (no prefix) toggles.
Inputs: tag (required), target.
take_region_screenshotA
Interactively capture a screen region: opens slurp so you can click-drag a selection on your actual screen right now, then captures it with grim. This blocks until a region is selected (Escape cancels). Requires grim and slurp.
Inputs: no named parameters.
take_screenshotA
Capture a screenshot with grim. Captures the whole layout (all monitors) by default, or a single output if 'monitor' is given. Requires grim to be installed.
Inputs: monitor.
toggle_floatingA
Toggle floating mode for a window (or the active one if no target given).
Inputs: target.
toggle_fullscreenC
Toggle fullscreen for the active window.
Inputs: mode.
toggle_groupA
Make a group from the active window (like i3wm's 'tabbed' container), or ungroup it if it's already grouped. Confirmed: hl.dsp.group.toggle().
Inputs: no named parameters.
toggle_group_lockA
Lock/unlock the active group so new windows can't (or can) join it automatically. Confirmed path: hl.dsp.group.lock(); exact toggle-vs-explicit-state argument shape isn't documented anywhere I could confirm, so this calls it with no arguments (assumed toggle, matching the pattern of group.toggle()). If it doesn't behave as expected, try hyprland_dispatch with a raw_expression like "hl.dsp.group.lock({ action = 'toggle' })" instead.
Inputs: no named parameters.
toggle_launcherA
Open Hyprland's first-party app launcher/picker (hyprlauncher), or close it if it's already open. hyprlauncher runs as a self-managing daemon: the first call starts the daemon and shows its window; every call after that just toggles the window, near-instantly, without restarting the daemon. Use this for 'open the launcher' / 'let me search for an app' style requests.
Inputs: no named parameters.
toggle_special_workspaceA
Show or hide a named special workspace (Hyprland's version of a scratchpad) on the current monitor. To put a window INTO a special workspace in the first place, use move_window_to_workspace with workspace set to 'special:' — this tool only toggles its visibility. Confirmed: hl.dsp.workspace.toggle_special('name') (bare string arg, not a table).
Inputs: name (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 48 tools
Most tools have clearly distinct purposes (e.g., close vs. kill, different screenshot types). A few may be confused (multiple move/resize tools, escape hatches overlap with some dedicated tools), but descriptions help disambiguate.
Naming mostly follows verb_noun pattern (close_window, focus_window). Some deviations: escape hatches (hyprctl_raw, hyprland_dispatch) and group_cycle break the pattern, but overall consistent.
48 tools is on the high side for a single server, covering many aspects. Some tools could be combined (e.g., multiple sunset tools), making the set feel heavy but still generally scoped.
Covers a wide range of Hyprland operations: window/workspace/monitor management, config, screenshots, notifications, launcher, sunset filter, etc. Minor gaps exist (e.g., no direct window rule manipulation), but escape hatches cover most.
Maintenance
Related MCP Connectors
Hosted Screenshots MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Hosted X Ads MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server for Hyprland desktop automation that allows AI assistants to see the screen, control mouse and keyboard, and manage windows using native Wayland tools. It integrates OCR for text-based interaction and supports complex multi-monitor setups with pixel-accurate coordinate mapping.276MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server that lets Claude Desktop and Claude Code control your PC — take screenshots, click, type, manage windows, and more.MIT
- AlicenseAqualityAmaintenanceAn MCP server for Hyprland that enables AI agents to control workspaces, windows, mouse, keyboard, and take screenshots on a Wayland desktop.14862 PyPI67MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for controlling Hyprland Wayland compositor: screen capture, mouse/keyboard injection, and automation via native Hyprland IPC and wlr protocols.MIT