hyprland-mcp

Claude가 hyprctl을 통해 Hyprland를 제어할 수 있게 해주는 MCP 서버입니다.

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 (물론) 및 PATH에 있는 hyprctl

• 선택 사항: 스크린샷용 grim + slurp, 알림용 notify-send (mako/dunst/유사), 앱 실행기 도구용 hyprlauncher, 블루라이트 필터 도구용 hyprsunset, 배경화면 도구용 hyprpaper (hyprpaper.conf의 기본값인 ipc = true 필요), 유휴/잠금 도구용 hypridle/hyprlock, 색상 선택기 도구용 hyprpicker (+ 자동 복사 옵션용 wl-clipboard), hypridle/hyprlock 및 hyprlauncher 도구용 pgrep/pkill (procps/procps-ng, 사실상 항상 기본 설치됨) — 이들은 모두 없으면 자연스럽게 기능이 축소되거나 명확한 오류를 냅니다.

빌드

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 하세요. 예:

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.* 형태가 바뀌면, 도구 핸들러 안에 묻혀 있는 호출 지점만 수정하지 말고 빌더와 해당 테스트를 함께 업데이트하세요.

실제로 개발 중에 이미 버그 하나를 잡아냈습니다. 타겟이 없는 denyWindowFromGroupExpr()은 깔끔한 () 대신 hl.dsp.window.deny_from_group({ })(빈 테이블)을 생성했는데, 그 이유는 빌더가 모든 키가 undefined인 경우에도 항상 args 객체를 전달했기 때문입니다. 타겟/셀렉터가 유일한 키가 될 수 있는 새 빌더를 추가할 때 알아두면 좋습니다. src/hyprctl.ts의 luaCall()은 이제 모두 undefined인 객체를 자동 감지해 단순한 path() 호출로 축소하지만, 명확하지 않은 경우에는 여전히 args 객체 전체를 조건부로 구성하는 것이 좋은 방법입니다. 비슷한 luaCall 개선(빈 테이블을 단순한 ()로 자동 축소)은 타겟 없이 호출될 때 clearWindowTagsExpr, bringWindowToTopExpr, centerWindowExpr, cycleNextWindowExpr, moveGroupWindowExpr의 동일한 예외 상황도 고쳤습니다.

보안 참고: unlock_screen

hyprlock에는 비밀번호를 인식하는 IPC가 없습니다. 문서화된 유일한 잠금 해제 메커니즘은 SIGUSR1(pkill -USR1 hyprlock)이며, 이 프로젝트의 unlock_screen 도구는 이를 직접 사용합니다. 즉, PAM/비밀번호 인증을 완전히 우회합니다. 이 MCP 도구를 호출할 수 있는 모든 것은 비밀번호를 몰라도 잠긴 세션을 잠금 해제할 수 있습니다. 이것은 버그나 실수가 아니라 hyprlock이 제공하는 유일한 잠금 해제 메커니즘입니다. 다만, 이 MCP 서버에 대한 접근 권한은 화면 잠금 자체의 보안 경계와 동등한 민감도로 취급해야 한다는 뜻입니다. 잠금 화면이 실제 장벽이어야 하는 곳(예: 공유 머신, 신뢰할 수 없는 머신)에는 그 점을 고려하지 않은 채 이 서버를 연결하지 마세요.

설계 노트

• hyprsunset과 hyprpaper는 각자의 hyprctl <name> <args> 하위 명령 계열(hyprctl hyprsunset ..., hyprctl hyprpaper ...)을 통해 제어합니다. keyword/getoption과 마찬가지로 이들은 0.55 Lua 디스패치 재작성의 영향을 받지 않으므로 src/tools/hyprsunset.ts와 hyprpaper.ts는 Lua 표현식 없이 runHyprctl()을 직접 호출합니다.

• 모든 hyprctl 호출은 execFile을 통해 이루어지므로(절대 셸을 거치지 않음) 인자가 셸 주입에 사용될 수 없습니다.

• 읽기 명령(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 관심사(예: 레이어, 장치, pin/특수 작업 공간)를 유지하면 프로젝트를 쉽게 탐색할 수 있습니다.