Hyprland MCP Server

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.