Skip to main content
Glama
hyprland-mcp

hyprland-mcp

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_swallow

  • Workspaces: list_workspaces, get_active_workspace, switch_workspace, move_workspace_to_monitor, rename_workspace, toggle_special_workspace, change_workspace_id, swap_monitor_workspaces

  • Monitors: list_monitors, focus_monitor, set_monitor_config

  • Config: get_config_option, set_config_option, reload_hyprland_config, get_hyprland_version

  • Keybinds: list_keybinds

  • Notifications: send_notification, dismiss_notifications

  • Screenshots: take_screenshot, take_region_screenshot (interactive, via slurp), screenshot_active_window

  • App 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_tags

  • Groups (tabbed containers): toggle_group, group_cycle, toggle_group_lock, deny_window_from_group, group_active_window, move_window_in_group

  • Cursor: move_cursor, move_cursor_to_corner, focus_direction

  • System: set_submap, exec_raw, exec_cmd, toggle_dpms, layout_message, list_instances, exit_hyprland

  • hyprsunset (blue light filter): set_sunset_temperature, disable_sunset_filter, set_sunset_gamma, reset_sunset, get_sunset_profile

  • hyprpaper (wallpaper): set_wallpaper, list_active_wallpapers

  • hypridle (idle management): start_hypridle, stop_hypridle, get_hypridle_status

  • hyprlock (screen lock): lock_screen, unlock_screen, refresh_lockscreen, get_lock_status, clear_crashed_lockscreen

  • hyprpicker (color picker): pick_color

  • Escape hatches: hyprland_dispatch (any hyprctl dispatch <dispatcher>), hyprctl_raw (any raw hyprctl subcommand)

Related MCP server: device-controller-mcp

Requirements

  • Node.js 18+

  • Hyprland (obviously) with hyprctl on PATH

  • Optional: grim + slurp for screenshots, notify-send (mako/dunst/similar) for notifications, hyprlauncher for the app launcher tools, hyprsunset for blue-light filter tools, hyprpaper (with ipc = true, the default, in hyprpaper.conf) for wallpaper tools, hypridle/hyprlock for idle/lock tools, hyprpicker (+ wl-clipboard for 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 build

This produces build/index.js.

Wire it up

Claude Code

claude mcp add hyprland -- node /absolute/path/to/hyprland-mcp/build/index.js

Claude 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 test

This 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

  • hyprsunset and hyprpaper are controlled through their own hyprctl <name> <args> subcommand families (hyprctl hyprsunset ..., hyprctl hyprpaper ...) — like keyword/getoption, these are untouched by the 0.55 Lua dispatch rewrite, so src/tools/hyprsunset.ts and hyprpaper.ts call runHyprctl() directly with no Lua expression involved.

  • All hyprctl calls go through execFile (never a shell), so arguments can never be used for shell injection.

  • Read commands (list_*, get_*) always go through hyprctl -j and 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_dispatch and hyprctl_raw exist as escape hatches for anything not yet wrapped (Hyprland adds dispatchers between releases) — check hyprctl dispatch --help or 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 tools
close_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

    A3.5/5.0

    Scored across 48 tools

    Disambiguation4/5

    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 Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessMixed handling

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An 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.
      27
      6
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that lets Claude Desktop and Claude Code control your PC — take screenshots, click, type, manage windows, and more.
      MIT
    • A
      license
      A
      quality
      A
      maintenance
      An MCP server for Hyprland that enables AI agents to control workspaces, windows, mouse, keyboard, and take screenshots on a Wayland desktop.
      14
      862 PyPI
      67
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for controlling Hyprland Wayland compositor: screen capture, mouse/keyboard injection, and automation via native Hyprland IPC and wlr protocols.
      MIT