🚀 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 的窗口管理、布局、输入等。

🧰 可用工具

💻 使用示例

基础用法

# 查询显示器信息
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 仓库
• 许可证