hyprland-mcp

Un servidor MCP que permite a Claude controlar Hyprland a través de hyprctl.

Se comunica con Hyprland mediante su socket IPC a través de hyprctl/hyprctl -j, y ejecuta externamente grim/slurp/notify-send para capturas de pantalla y notificaciones. Funciona sobre stdio, por lo que solo funciona cuando se inicia dentro de tu sesión de Hyprland (o con HYPRLAND_INSTANCE_SIGNATURE reenviado a él).

Herramientas

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

• Espacios de trabajo: list_workspaces, get_active_workspace, switch_workspace, move_workspace_to_monitor, rename_workspace, toggle_special_workspace, change_workspace_id, swap_monitor_workspaces

• Monitores: list_monitors, focus_monitor, set_monitor_config

• Configuración: get_config_option, set_config_option, reload_hyprland_config, get_hyprland_version

• Atajos de teclado: list_keybinds

• Notificaciones: send_notification, dismiss_notifications

• Capturas de pantalla: take_screenshot, take_region_screenshot (interactivo, mediante slurp), screenshot_active_window

• Lanzador de aplicaciones: toggle_launcher, prewarm_launcher_daemon (controla hyprlauncher, el selector de aplicaciones oficial de Hyprland — un demonio que se autoactiva, no un despachador de hyprctl)

• Etiquetas: tag_window, clear_window_tags

• Grupos (contenedores con pestañas): 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

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

• hyprsunset (filtro de luz azul): set_sunset_temperature, disable_sunset_filter, set_sunset_gamma, reset_sunset, get_sunset_profile

• hyprpaper (fondo de pantalla): set_wallpaper, list_active_wallpapers

• hypridle (gestión de inactividad): start_hypridle, stop_hypridle, get_hypridle_status

• hyprlock (bloqueo de pantalla): lock_screen, unlock_screen, refresh_lockscreen, get_lock_status, clear_crashed_lockscreen

• hyprpicker (selector de color): pick_color

• Vías de escape: hyprland_dispatch (cualquier hyprctl dispatch <dispatcher>), hyprctl_raw (cualquier subcomando hyprctl sin procesar)

Related MCP server: device-controller-mcp

Requisitos

• Node.js 18+

• Hyprland (obviamente) con hyprctl en PATH

• Opcional: grim + slurp para capturas de pantalla, notify-send (mako/dunst/similar) para notificaciones, hyprlauncher para las herramientas del lanzador de aplicaciones, hyprsunset para las herramientas del filtro de luz azul, hyprpaper (con ipc = true, el valor predeterminado, en hyprpaper.conf) para las herramientas de fondo de pantalla, hypridle/hyprlock para las herramientas de inactividad/bloqueo, hyprpicker (+ wl-clipboard para su opción de autocopia) para la herramienta de selector de color, pgrep/pkill (procps/procps-ng, prácticamente siempre preinstalados) para las herramientas de hypridle/hyprlock y hyprlauncher — todas estas se degradan correctamente o muestran un error claro si faltan.

Compilación

npm install
npm run build

Esto produce build/index.js.

Conectarlo

Claude Code

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

Claude Desktop

Añadir a claude_desktop_config.json:

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

Claude Desktop en Linux es iniciado por tu sesión, por lo que HYPRLAND_INSTANCE_SIGNATURE ya debería estar en su entorno. Si alguna vez ejecutas esto desde un contexto que no lo tenga (por ejemplo, una unidad systemd, una sesión SSH, o esta misma herramienta ejecutando Claude Code desde dentro de un sandbox), expórtalo primero, por ejemplo:

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

Pruebas

src/dispatch-expressions.ts contiene constructores puros, sin efectos secundarios, para cada expresión Lua que este proyecto envía a hyprctl dispatch — sin llamadas a hyprctl/child_process, por lo que se pueden probar unitariamente sin una sesión real de Hyprland:

npm test

Esto ejecuta tsc y luego el ejecutor de pruebas integrado de Node sobre src/__tests__/dispatch-expressions.test.ts, verificando la cadena exacta que produce cada constructor — incluyendo los dos ejemplos textuales de la wiki (window.tag con un objetivo, el argumento de cadena simple de workspace.toggle_special). Esto es lo que realmente detecta la deriva sintáctica: cuando una versión futura de Hyprland cambie la forma de un hl.dsp.*, actualiza el constructor y su prueba juntos, en lugar de tocar solo el punto de llamada oculto dentro de un manejador de herramienta.

Ya detectó un error real durante el desarrollo: denyWindowFromGroupExpr() sin objetivo estaba emitiendo hl.dsp.window.deny_from_group({ }) (una tabla vacía) en lugar de un () limpio, porque el constructor siempre pasaba un objeto de argumentos incluso cuando cada clave en él era undefined. Vale la pena saberlo si agregas un nuevo constructor donde un objetivo/selector sea la única clave posible — luaCall() en src/hyprctl.ts ahora detecta automáticamente objetos con todos los valores undefined y los colapsa a una llamada path() simple, pero sigue siendo una buena práctica construir todo el objeto de argumentos condicionalmente para casos no obvios. Una mejora similar de luaCall (colapsar automáticamente tablas vacías a () simple) también corrigió el mismo caso límite para clearWindowTagsExpr, bringWindowToTopExpr, centerWindowExpr, cycleNextWindowExpr y moveGroupWindowExpr cuando se llaman sin objetivos.

Nota de seguridad: unlock_screen

hyprlock no tiene IPC consciente de contraseñas — su único mecanismo de desbloqueo documentado es SIGUSR1 (pkill -USR1 hyprlock), que la herramienta unlock_screen de este proyecto utiliza directamente. Eso significa que omite por completo la autenticación PAM/contraseña: cualquier cosa que pueda invocar esta herramienta MCP puede desbloquear una sesión bloqueada sin conocer la contraseña. Esto no es un error ni un descuido, es el único mecanismo de desbloqueo que hyprlock expone — pero significa que el acceso a este servidor MCP debe tratarse como equivalente en sensibilidad al propio límite de seguridad de tu bloqueo de pantalla. No conectes este servidor en un lugar donde se suponga que un bloqueo de pantalla sea una barrera real (por ejemplo, una máquina compartida/no confiable) sin tenerlo en cuenta.

Notas de diseño

• hyprsunset y hyprpaper se controlan a través de sus propias familias de subcomandos hyprctl <nombre> <args> (hyprctl hyprsunset ..., hyprctl hyprpaper ...) — al igual que keyword/getoption, estos no se ven afectados por la reescritura de despacho Lua 0.55, por lo que src/tools/hyprsunset.ts y hyprpaper.ts llaman a runHyprctl() directamente sin ninguna expresión Lua involucrada.

• Todas las llamadas a hyprctl pasan por execFile (nunca un shell), por lo que los argumentos nunca pueden usarse para inyección de shell.

• Los comandos de lectura (list_*, get_*) siempre pasan por hyprctl -j y se analizan como JSON para que Claude reciba datos estructurados, no texto que deba examinar.

• Cada herramienta dedicada es un envoltorio delgado alrededor de un despachador/subcomando específico. hyprland_dispatch y hyprctl_raw existen como vías de escape para cualquier cosa que aún no esté envuelta (Hyprland añade despachadores entre versiones) — consulta hyprctl dispatch --help o la wiki de Hyprland para obtener la lista completa.

• Las herramientas de captura de pantalla escriben en un directorio temporal, codifican en base64 y se limpian después.

• Las herramientas de mover/redimensionar utilizan las convenciones de argumentos de despachador exact/relativo de Hyprland (moveactive, resizeactive) en lugar de reimplementar cálculos geométricos.

Extensión

Añade un nuevo archivo en src/tools/, exporta una función register*Tools(server) y llámala desde src/index.ts. Mantén un asunto de hyprctl por archivo (por ejemplo, capas, dispositivos, ventanas ancladas/especiales) para que el proyecto sea fácil de navegar.