Hyprland MCP Server

https://github.com/user-attachments/assets/b4fc1d26-ec04-451a-b7c9-7f87b44d9c9e

Hyprland Wayland コンポジターのコマンドラインインターフェースである hyprctl のすべての機能を、言語モデルに公開する軽量な非公式のModel Context Protocol（MCP）サーバーです。

このサーバーにより、自然言語インターフェースを通じて、Hyprland のウィンドウ管理、レイアウト、入力などを照会および制御できます。

注： このプロジェクトは実験段階であり、ベータ版です。

🚀 クイックスタート

1. リポジトリをクローンします

git clone https://github.com/stefanoamorelli/hyprmcp.git
cd hyprmcp

2. HYPRLAND_INSTANCE_SIGNATURE を取得します

echo $HYPRLAND_INSTANCE_SIGNATURE

3. MCP クライアントにサーバーをインストールします

たとえば、Claude Desktop では、~/.config/Claude/claude_desktop_config.json ファイルを次のように変更します。

"Hyperland MCP Server": {
  "command": "uv",
  "args": [
    "run",
    "--with",
    "mcp[cli]",
    "--with",
    "subprocess",
    "mcp",
    "run",
   "<global path of the repo>/hyprmcp/hyprmcp/server.py"
  ],
  "env": {
    "PYTHONPATH": "<global path of the repo>/hyprmcp",
    "HYPRLAND_INSTANCE_SIGNATURE": "<your-hyprland-instance-signature>"
  }
},

🧰 利用可能なツール

ツール名	説明
run_hyprctl_command	任意の hyprctl コマンドを実行します。
get_version	Hyprland のバージョンとビルド情報を取得します。
list_monitors	接続されているすべてのモニターとプロパティを一覧表示します。
list_workspaces	アクティブなすべてのワークスペースを一覧表示します。
list_clients	すべてのウィンドウとそのプロパティを一覧表示します。
list_devices	接続されているすべての入力デバイスを一覧表示します。
get_active_window	現在アクティブなウィンドウの詳細を表示します。
list_layers	コンポジター内のすべてのレイヤーを表示します。
get_splash	現在のランダムなスプラッシュメッセージを取得します。
dispatch_command	Hyprland にコマンドを送信します。
set_keyword	設定キーワードを動的に設定します。
reload_config	Hyprland の設定ファイルを強制的に再読み込みします。
enter_kill_mode	クリックしてウィンドウを終了できるキルモードを有効にします。

これらのツールを使うと、言語モデルから Hyprland の機能をシームレスに操作できます。

💡 使用例

ユーザープロンプト：「ワークスペース 2 に切り替えてください。」

MCP サーバーの動作： hyprctl dispatch workspace 2 を実行します。

ユーザープロンプト：「現在アクティブなウィンドウは何ですか？」

MCP サーバーの動作： hyprctl activewindow -j を実行し、詳細を返します。

🛠️ 開発

開発用にサーバーをローカルで実行するには、次のコマンドを実行します。

mcp dev server.py

Hyprland が実行中であり、必要な環境変数が設定されていることを確認してください。

📚 参考資料

• Hyprland のドキュメント
• Model Context Protocol
• Python MCP SDK

📜 ライセンス

MIT ライセンス © 2025 Stefano Amorelli