hyprland-mcp

ClaudeがHyprlandをhyprctl経由で制御できるようにする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 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を実行し、各ビルダーが生成する正確な文字列をアサートします — 2つの逐語的なwikiの例（ターゲット付きのwindow.tag、workspace.toggle_specialのベア文字列引数）を含みます。これが実際に構文のずれをキャッチする方法です: 将来のHyprlandリリースがhl.dsp.*の形状を変更した場合、ツールハンドラー内に埋もれた呼び出し箇所だけを触るのではなく、ビルダーとそのテストを一緒に更新します。

開発中に実際のバグを1つすでにキャッチしました: ターゲットなしの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）であり、このプロジェクトの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 wikiを確認してください。

• スクリーンショットツールは一時ディレクトリに書き込み、base64エンコードし、その後クリーンアップします。

• 移動/リサイズツールは、ジオメトリ計算を再実装するのではなく、Hyprlandのexact/相対ディスパッチャー引数規則（moveactive、resizeactive）を使用します。

拡張

src/tools/の下に新しいファイルを追加し、register*Tools(server)関数をエクスポートし、src/index.tsから呼び出します。プロジェクトをナビゲートしやすく保つために、1ファイルにつき1つのhyprctl関心事（例: レイヤー、デバイス、ピン/特殊ワークスペース）を維持してください。