hyprland-mcp

一个 MCP 服务器，让 Claude 能够通过 hyprctl 控制 Hyprland。

通过 hyprctl/hyprctl -j 与 Hyprland 的 IPC 套接字通信，并通过 grim/slurp/notify-send 执行截图和通知功能。运行在 stdio 上，因此必须在 Hyprland 会话内启动（或通过 HYPRLAND_INSTANCE_SIGNATURE 环境变量转发）。

工具

• 窗口：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

• 工作区：list_workspaces、get_active_workspace、switch_workspace、 move_workspace_to_monitor、rename_workspace、toggle_special_workspace、 change_workspace_id、swap_monitor_workspaces

• 显示器：list_monitors、focus_monitor、set_monitor_config

• 配置：get_config_option、set_config_option、reload_hyprland_config、 get_hyprland_version

• 快捷键：list_keybinds

• 通知：send_notification、dismiss_notifications

• 截图：take_screenshot、take_region_screenshot（交互式，通过 slurp）、 screenshot_active_window

• 应用启动器：toggle_launcher、prewarm_launcher_daemon（控制 hyprlauncher，Hyprland 官方 应用选择器——一个自切换守护进程，不是 hyprctl 调度器）

• 标签：tag_window、clear_window_tags

• 分组（标签页容器）：toggle_group、group_cycle、toggle_group_lock、 deny_window_from_group、group_active_window、move_window_in_group

• 光标：move_cursor、move_cursor_to_corner、focus_direction

• 系统：set_submap、exec_raw、exec_cmd、toggle_dpms、layout_message、 list_instances、exit_hyprland

• hyprsunset（蓝光滤镜）：set_sunset_temperature、disable_sunset_filter、 set_sunset_gamma、reset_sunset、get_sunset_profile

• hyprpaper（壁纸）：set_wallpaper、list_active_wallpapers

• hypridle（空闲管理）：start_hypridle、stop_hypridle、get_hypridle_status

• hyprlock（屏幕锁定）：lock_screen、unlock_screen、refresh_lockscreen、 get_lock_status、clear_crashed_lockscreen

• hyprpicker（取色器）：pick_color

• 逃生口：hyprland_dispatch（任意 hyprctl dispatch <dispatcher>）、 hyprctl_raw（任意原始 hyprctl 子命令）

Related MCP server: device-controller-mcp

要求

• Node.js 18+

• Hyprland（显然）且 hyprctl 在 PATH 中

• 可选：grim + slurp 用于截图，notify-send（mako/dunst/类似工具）用于 通知，hyprlauncher 用于应用 启动器工具，hyprsunset 用于蓝光 滤镜工具，hyprpaper（需要在 hyprpaper.conf 中设置 ipc = true，默认值）用于壁纸工具， hypridle/hyprlock 用于空闲/锁定工具，hyprpicker（+ wl-clipboard 用于其自动复制选项）用于取色器工具，pgrep/pkill （procps/procps-ng，几乎总是预装）用于 hypridle/hyprlock 和 hyprlauncher 工具——如果缺少这些工具，会优雅降级或明确报错

构建

npm install
npm run build

这将生成 build/index.js。

配置连接

Claude Code

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

Claude Desktop

添加到 claude_desktop_config.json：

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

Linux 上的 Claude Desktop 由你的会话启动，因此 HYPRLAND_INSTANCE_SIGNATURE 应该已经在它的环境中。如果你在缺少该环境变量的上下文中运行（例如 systemd 单元、 SSH 会话，或同一工具在沙箱内运行 Claude Code），请先导出它，例如：

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

测试

src/dispatch-expressions.ts 包含该项目发送给 hyprctl dispatch 的每个 Lua 表达式的纯构建器，无副作用——不调用 hyprctl/child_process，因此可以在没有 真实 Hyprland 会话的情况下进行单元测试：

npm test

这会运行 tsc，然后使用 Node 内置的测试运行器执行 src/__tests__/dispatch-expressions.test.ts，断言每个构建器生成的精确字符串—— 包括两个逐字维基示例（带目标的 window.tag，以及 workspace.toggle_special 的裸字符串参数）。这实际上能捕获语法漂移：当未来的 Hyprland 版本更改 hl.dsp.* 的形状时，同时更新构建器和它的测试，而不是只修改隐藏在工具处理器 内部的调用点。

在开发过程中，它已经捕获了一个真实 bug：denyWindowFromGroupExpr() 在没有 目标时生成了 hl.dsp.window.deny_from_group({ })（一个空表），而不是干净的 ()，因为构建器总是传递一个 args 对象，即使其中的每个键都是 undefined。 如果你添加一个新的构建器，其中目标/选择器是唯一可能的键，这一点值得注意—— src/hyprctl.ts 中的 luaCall() 现在会自动检测全 undefined 的对象并将其 折叠为裸的 path() 调用，但最佳实践仍然是在非明显的情况下有条件地构建整个 args 对象。类似的 luaCall 改进（自动将空表折叠为裸的 ()）也修复了 clearWindowTagsExpr、bringWindowToTopExpr、centerWindowExpr、 cycleNextWindowExpr 和 moveGroupWindowExpr 在无目标调用时的相同边缘情况。

安全说明：unlock_screen

hyprlock 没有密码感知的 IPC——其唯一文档化的解锁机制是 SIGUSR1（pkill -USR1 hyprlock），该项目直接使用该机制。这意味着它 绕过了 PAM/密码认证：任何能够调用此 MCP 工具的人都可以在不知道密码的 情况下解锁锁定的会话。这不是 bug 或疏忽，而是 hyprlock 暴露的唯一解锁机制—— 但这确实意味着对此 MCP 服务器的访问应被视为与屏幕锁定本身的安全边界具有 相同的敏感性。不要将这台服务器连接到屏幕锁定旨在作为真正屏障的地方（例如 共享/不受信任的机器），而不考虑这一点。

设计说明

• hyprsunset 和 hyprpaper 通过它们自己的 hyprctl <name> <args> 子命令家族控制（hyprctl hyprsunset ...、hyprctl hyprpaper ...）—— 与 keyword/getoption 一样，这些不受 0.55 Lua 调度重写的影响，因此 src/tools/hyprsunset.ts 和 hyprpaper.ts 直接调用 runHyprctl()，不涉及 Lua 表达式。

• 所有 hyprctl 调用都通过 execFile（从不使用 shell），因此参数永远不会被 用于 shell 注入。

• 读取命令（list_*、get_*）始终通过 hyprctl -j 并解析为 JSON，这样 Claude 获得结构化数据，而不是需要肉眼检查的文本。

• 每个专用工具都是特定调度器/子命令的薄封装。 hyprland_dispatch 和 hyprctl_raw 作为尚未封装的任何功能的逃生口存在 （Hyprland 在版本之间添加调度器）——查看 hyprctl dispatch --help 或 Hyprland 维基 获取 完整列表。

• 截图工具写入临时目录，进行 base64 编码，然后自行清理。

• 移动/调整大小工具使用 Hyprland 的 exact/相对调度器参数约定 （moveactive、resizeactive），而不是重新实现几何数学。

扩展

在 src/tools/ 下添加新文件，导出一个 register*Tools(server) 函数，然后 从 src/index.ts 中调用它。保持每个文件处理一个 hyprctl 关注点（例如层、 设备、固定/特殊工作区），以便项目易于导航。