hyprland-mcp

Ein MCP-Server, der es Claude ermöglicht, Hyprland über hyprctl zu steuern.

Kommuniziert mit Hyprland über dessen IPC-Socket mittels hyprctl/hyprctl -j und ruft grim/slurp/notify-send für Screenshots und Benachrichtigungen auf. Läuft über stdio, funktioniert also nur, wenn es innerhalb deiner Hyprland-Sitzung gestartet wird (oder wenn HYPRLAND_INSTANCE_SIGNATURE an es weitergereicht wird).

Werkzeuge

• Fenster: 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

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

• Monitore: list_monitors, focus_monitor, set_monitor_config

• Konfiguration: get_config_option, set_config_option, reload_hyprland_config, get_hyprland_version

• Tastenkürzel: list_keybinds

• Benachrichtigungen: send_notification, dismiss_notifications

• Screenshots: take_screenshot, take_region_screenshot (interaktiv, über slurp), screenshot_active_window

• App-Launcher: toggle_launcher, prewarm_launcher_daemon (steuert hyprlauncher, Hyprlands offiziellen App-Picker — einen Daemon, der sich selbst ein- und ausschaltet, keinen hyprctl-Dispatcher)

• Tags: tag_window, clear_window_tags

• Gruppen (Tab-Container): 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 (Blaulichtfilter): set_sunset_temperature, disable_sunset_filter, set_sunset_gamma, reset_sunset, get_sunset_profile

• hyprpaper (Hintergrundbild): set_wallpaper, list_active_wallpapers

• hypridle (Idle-Verwaltung): start_hypridle, stop_hypridle, get_hypridle_status

• hyprlock (Bildschirmsperre): lock_screen, unlock_screen, refresh_lockscreen, get_lock_status, clear_crashed_lockscreen

• hyprpicker (Farbwähler): pick_color

• Ausweichmöglichkeiten: hyprland_dispatch (beliebiger hyprctl dispatch <dispatcher>), hyprctl_raw (beliebiges rohes hyprctl-Unterkommando)

Related MCP server: device-controller-mcp

Voraussetzungen

• Node.js 18+

• Hyprland (natürlich) mit hyprctl im PATH

• Optional: grim + slurp für Screenshots, notify-send (mako/dunst/ähnliche) für Benachrichtigungen, hyprlauncher für die App-Launcher-Werkzeuge, hyprsunset für Blaulichtfilter-Werkzeuge, hyprpaper (mit ipc = true, der Standardeinstellung, in hyprpaper.conf) für Hintergrundbild-Werkzeuge, hypridle/hyprlock für Idle-/Sperr-Werkzeuge, hyprpicker (+ wl-clipboard für dessen Autokopier-Option) für das Farbwähler-Werkzeug, pgrep/pkill (procps/procps-ng, praktisch immer vorinstalliert) für die hypridle/hyprlock- und hyprlauncher-Werkzeuge – all diese degradieren elegant oder melden einen klaren Fehler, wenn sie fehlen.

Erstellen

npm install
npm run build

Dies erzeugt build/index.js.

Anbinden

Claude Code

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

Claude Desktop

Füge zu claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "hyprland": {
      "command": "node",
      "args": ["/absolute/path/to/hyprland-mcp/build/index.js"]
    }
  }
}

Claude Desktop wird unter Linux von deiner Sitzung gestartet, daher sollte HYPRLAND_INSTANCE_SIGNATURE bereits in seiner Umgebung vorhanden sein. Falls du diesen Server jemals aus einem Kontext ausführst, in dem diese Variable nicht vorhanden ist (z. B. in einer systemd-Unit, einer SSH-Sitzung, oder wenn dasselbe Werkzeug Claude Code aus einer Sandbox heraus startet), exportiere sie zuerst, z. B.:

export HYPRLAND_INSTANCE_SIGNATURE=$(ls /tmp/hypr | head -n1)

Testen

src/dispatch-expressions.ts enthält reine, nebenwirkungsfreie Builder für jeden Lua-Ausdruck, den dieses Projekt an hyprctl dispatch sendet — ohne hyprctl/child_process-Aufrufe, sodass sie ohne echte Hyprland-Sitzung unit-testbar sind:

npm test

Dies führt tsc und dann den in Node.js eingebauten Test-Runner über src/__tests__/dispatch-expressions.test.ts aus und prüft die exakte Zeichenkette, die jeder Builder erzeugt — einschließlich der beiden wörtlich übernommenen Wiki-Beispiele (window.tag mit einem Ziel, das reine String-Argument von workspace.toggle_special). Genau das fängt Syntax-Drift ab: Wenn eine zukünftige Hyprland-Version eine hl.dsp.*-Form ändert, aktualisiere den Builder und seinen Test gemeinsam, anstatt nur die Aufrufstelle zu ändern, die tief in einem Werkzeug-Handler vergraben ist.

Es hat während der Entwicklung bereits einen echten Bug gefunden: denyWindowFromGroupExpr() ohne Ziel erzeugte hl.dsp.window.deny_from_group({ }) (eine leere Tabelle) statt eines sauberen (), weil der Builder immer ein Args-Objekt übergab, selbst wenn jeder Schlüssel darin undefined war. Wissenswert, wenn du einen neuen Builder hinzufügst, bei dem ein Ziel/Selektor der einzige mögliche Schlüssel ist — luaCall() in src/hyprctl.ts erkennt inzwischen automatisch Objekte, deren Werte alle undefined sind, und reduziert sie auf einen bloßen path()-Aufruf, aber es ist trotzdem gute Praxis, das gesamte Args-Objekt bei nicht offensichtlichen Fällen bedingt aufzubauen. Eine ähnliche luaCall-Verbesserung (automatisches Reduzieren leerer Tabellen auf ein bloßes ()) behob denselben Randfall auch für clearWindowTagsExpr, bringWindowToTopExpr, centerWindowExpr, cycleNextWindowExpr und moveGroupWindowExpr, wenn sie ohne Ziele aufgerufen werden.

Sicherheitshinweis: unlock_screen

hyprlock verfügt über kein IPC mit Passwortprüfung – sein einziger dokumentierter Entsperrmechanismus ist SIGUSR1 (pkill -USR1 hyprlock), den das unlock_screen-Werkzeug dieses Projekts direkt verwendet. Das bedeutet, dass es PAM-/Passwort-Authentifizierung vollständig umgeht: Alles, was dieses MCP-Werkzeug aufrufen kann, kann eine gesperrte Sitzung entsperren, ohne das Passwort zu kennen. Das ist kein Bug und kein Versehen, sondern der einzige Entsperrmechanismus, den hyprlock bereitstellt – aber es bedeutet, dass der Zugriff auf diesen MCP-Server genauso sensibel behandelt werden sollte wie die Sicherheitsgrenze deiner Bildschirmsperre selbst. Binde diesen Server nicht an einem Ort ein, an dem eine Bildschirmsperre eine echte Barriere sein soll (z. B. einem geteilten/nicht vertrauenswürdigen Rechner), ohne das zu berücksichtigen.

Designhinweise

• hyprsunset und hyprpaper werden über ihre eigenen hyprctl <name> <args>-Subkommandofamilien gesteuert (hyprctl hyprsunset ..., hyprctl hyprpaper ...) — wie keyword/getoption sind diese von der 0.55-Neufassung des Lua-Dispatch unberührt, daher rufen src/tools/hyprsunset.ts und hyprpaper.ts runHyprctl() direkt auf, ohne dass ein Lua-Ausdruck involviert ist.

• Alle hyprctl-Aufrufe laufen über execFile (niemals über eine Shell), daher können Argumente nie für Shell-Injection verwendet werden.

• Lese-Befehle (list_*, get_*) laufen immer über hyprctl -j und werden als JSON geparst, sodass Claude strukturierte Daten erhält, statt Text zum Durchsehen.

• Jedes dedizierte Werkzeug ist ein dünner Wrapper um einen bestimmten Dispatcher/ein bestimmtes Unterkommando. hyprland_dispatch und hyprctl_raw dienen als Ausweichmöglichkeiten für alles, was noch nicht von einem Wrapper abgedeckt ist (Hyprland fügt zwischen Releases neue Dispatcher hinzu) — prüfe hyprctl dispatch --help oder das Hyprland-Wiki für die vollständige Liste.

• Screenshot-Werkzeuge schreiben in ein temporäres Verzeichnis, kodieren base64 und räumen danach selbst auf.

• Move-/Resize-Werkzeuge verwenden Hyprlands exact/relative Dispatcher-Argumentkonventionen (moveactive, resizeactive), anstatt Geometrie-Mathematik neu zu implementieren.

Erweitern

Füge eine neue Datei unter src/tools/ hinzu, exportiere eine register*Tools(server)-Funktion und rufe sie aus src/index.ts auf. Behalte genau einen hyprctl-Zuständigkeitsbereich (z. B. Ebenen, Geräte, Pin/Special-Workspaces) pro Datei bei, damit das Projekt leicht zu navigieren ist.