<div align="center">

Hyprland MCP 服务器

</div> <div align="center">

</div>

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

一个轻量级的、非官方的 Model Context Protocol (MCP) 服务器，它暴露了 hyprctl —— Hyprland Wayland 组合器的命令行接口——的所有功能给语言模型。

此服务器使自然语言界面能够查询和控制 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 服务器": {
  "command": "uv",
  "args": [
    "run",
    "--with",
    "mcp[cli]",
    "--with",
    "subprocess",
    "mcp",
    "run",
   "<全局路径到仓库>/hyprmcp/hyprmcp/server.py"
  ],
  "env": {
    "PYTHONPATH": "<全局路径到仓库>/hyprmcp",
    "HYPRLAND_INSTANCE_SIGNATURE": "<你的-hyprland实例签名>"
  }
},

🧰 可用工具

工具名称	描述
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