Hyprland MCP Server

Name: Hyprland MCP Server
Author: stefanoamorelli

@stefanoamorelli

代码仓库

关于 Hyprland MCP Server

Community MCP server for hyprctl

基本信息

分类

其他

许可证

MIT license

运行时

python

传输方式

stdio

发布者

stefanoamorelli

配置

暂无标准配置

该服务器的 README 中没有可解析的 MCP 配置块，请前往代码仓库查看安装说明。

代码仓库

工具

未检测到工具

工具是从 README 中自动提取的。维护者可以在 ## Tools 标题下列出工具,即可填充这部分内容。

概览

What is Hyprland MCP Server?

Hyprland MCP Server is a lightweight, unofficial Model Context Protocol (MCP) server that exposes the full functionality of hyprctl—the command-line interface for the Hyprland Wayland compositor—to language models. It enables natural language interfaces to query and control Hyprland’s window management, layouts, inputs, and more.

How to use Hyprland MCP Server?

Clone the repository, obtain your HYPRLAND_INSTANCE_SIGNATURE environment variable, then configure the server in your MCP client (e.g., Claude Desktop) by editing ~/.config/Claude/claude_desktop_config.json with the uv run command and required environment variables. For development, run mcp dev server.py locally while Hyprland is running.

Key features of Hyprland MCP Server

Executes arbitrary hyprctl commands via run_hyprctl_command.
Retrieves Hyprland version, monitors, workspaces, clients, and devices.
Shows active window details and compositor layers.
Dispatches commands to Hyprland for window/workspace control.
Dynamically sets configuration keywords with set_keyword.
Reloads the Hyprland config file and enters kill mode.

Use cases of Hyprland MCP Server

Switch to a specific workspace or move windows using natural language.
Query details of the currently active window or all connected monitors.
List all open windows and their properties for inventory or automation.
Dispatch Hyprland commands (e.g., toggle floating, change layout) via chat.
Dynamically adjust Hyprland settings like gaps, borders, or input behavior.

FAQ from Hyprland MCP Server

Is Hyprland MCP Server an official Hyprland tool?

No, it is an unofficial, community-maintained server and is currently in beta.

What are the runtime requirements?

Python 3.10+ and the uv package manager are required. The server runs only on Linux with Hyprland active, and the HYPRLAND_INSTANCE_SIGNATURE environment variable must be set.

How does the server communicate with Hyprland?

It invokes hyprctl commands (with optional JSON output) via subprocess, using the instance signature for authentication. No separate authentication step is needed.

What transports does the server use?

It uses the standard MCP protocol transport (stdio) as defined in the MCP specification. No custom transports are supported.

Are there any known limitations?

This is an experimental beta release; reliability and full coverage of all hyprctl features are not guaranteed. The server must run on the same machine as the Hyprland session.