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.