hyprland-mcp

MCP-сервер, позволяющий Claude управлять Hyprland через hyprctl.

Общается с Hyprland через его IPC-сокет с помощью hyprctl/hyprctl -j, и вызывает внешние утилиты 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 (с ipc = true, по умолчанию, в hyprpaper.conf) для инструментов обоев, 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"]
    }
  }
}

Claude Desktop в Linux запускается вашим сеансом, поэтому HYPRLAND_INSTANCE_SIGNATURE уже должен быть в его окружении. Если вы когда-либо запускаете это из контекста, где его нет (например, systemd-юнит, SSH-сессия или этот же инструмент, запускающий Claude Code внутри песочницы), сначала экспортируйте его, например:

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

Тестирование

src/dispatch-expressions.ts содержит чистые, не имеющие побочных эффектов построители для каждого Lua-выражения, которое этот проект отправляет в hyprctl dispatch — без вызовов 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. Стоит знать, если вы добавляете новый построитель, где цель/селектор является единственным возможным ключом — luaCall() в src/hyprctl.ts теперь автоматически обнаруживает объекты со всеми undefined и сворачивает их в простой вызов path(), но всё равно хорошей практикой будет строить весь объект аргументов условно для неочевидных случаев. Аналогичное улучшение 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, они не затронуты переписыванием Lua-диспетчера в версии 0.55, поэтому src/tools/hyprsunset.ts и hyprpaper.ts вызывают runHyprctl() напрямую без использования Lua-выражений.

• Все вызовы hyprctl проходят через execFile (никогда через оболочку), поэтому аргументы никогда не могут быть использованы для внедрения команд оболочки.

• Команды чтения (list_*, get_*) всегда проходят через hyprctl -j и парсятся как JSON, чтобы Claude получал структурированные данные, а не текст для просмотра глазами.

• Каждый выделенный инструмент — это тонкая обёртка вокруг конкретного диспетчера/подкоманды. hyprland_dispatch и hyprctl_raw существуют как запасные выходы для всего, что ещё не обёрнуто (Hyprland добавляет диспетчеры между релизами) — проверьте hyprctl dispatch --help или вики Hyprland для полного списка.

• Инструменты скриншотов записывают во временную директорию, кодируют в base64 и очищают за собой.

• Инструменты перемещения/изменения размера используют соглашения о аргументах диспетчера exact/relative Hyprland (moveactive, resizeactive), а не перереализуют геометрические вычисления.

Расширение

Добавьте новый файл в src/tools/, экспортируйте функцию register*Tools(server) и вызовите её из src/index.ts. Держите одну область ответственности hyprctl (например, слои, устройства, закреплённые/специальные рабочие пространства) в одном файле, чтобы проектом было легко ориентироваться.