Hyprland MCP Server

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

这是一个轻量、非官方的模型上下文协议（MCP）服务，可将 hyprctl 的全部功能开放给大模型。hyprctl 是用于 Hyprland Wayland 合成器的命令行接口。

此服务支持通过自然语言界面查询和控制 Hyprland 的窗口管理、布局、输入设备等功能。

注意： 此项目仍处于实验阶段，当前为 Beta 版。

🚀 快速开始

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 文档
• 模型上下文协议
• Python MCP SDK

📜 许可证

MIT 许可证 © 2025 Stefano Amorelli