hyprmcp

🚀 Hyprland MCP 服务器

这是一个轻量级的、非官方的模型上下文协议 (MCP) 服务器，它将 hyprctl（Hyprland 的命令行界面——Hyprland Wayland 合成器的 CLI）的所有功能开放出来，让语言模型可以查询和控制 Hyprland 的窗口管理、布局、输入等功能。通过自然语言接口，用户能够方便地查询并控制 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>"
  }
},

✨ 主要特性

此服务器暴露了 hyprctl 的所有功能，提供了自然语言接口，允许查询并控制 Hyprland 的窗口管理、布局、输入等。

🧰 可用工具

| 工具名称 | 描述 | |-----------------------|-------------------------------------------| | run_hyprctl_command | 执行任意的 hyprctl 命令。 | | get_version | 获取 Hyprland 的版本和构建信息。 | | list_monitors | 列出所有连接的显示器及其属性。 | | list_workspaces | 列出所有活动工作区。 | | list_clients | 列出所有窗口及其属性。 | | list_devices | 列出所有连接的输入设备。 | | get_active_window | 显示当前活动窗口的详细信息。 | | list_layers | 显示合成器中的所有层。 | | get_compositor_info| 获取合成器的信息。 | | get_keybindings | 获取所有键盘快捷键。 | | get_modifications | 获取对配置文件的修改。 | | reload_config | 重新加载配置文件。 |

💻 使用示例

基础用法

# 查询显示器信息
mcp run hyperland_mcp_server.list_monitors

# 查询窗口信息
mcp run hyperland_mcp_server.get_active_window

# 查询工作区信息
mcp run hyperland_mcp_server.list_workspaces

🛠️ 开发说明

# 运行服务器
python3 -m hyperland_mcp_server

📄 许可证

参考资料

• MCP 协议
• Hyprland 仓库
• 许可证