Hyprland MCP Server

Hyprland MCP Server

What is Hyprland MCP Server about?

Hyprland MCP Server offers a Model Context Protocol interface to the Hyprland compositor. By wrapping the hyprctl command‑line tool, it allows AI agents to retrieve information about monitors, workspaces, windows, input devices, and to dispatch actions such as switching workspaces, killing windows, or reloading the configuration.

How to use Hyprland MCP Server?

1. Clone the repository and navigate into the project directory.
2. Obtain your HYPRLAND_INSTANCE_SIGNATURE environment variable (e.g., echo $HYPRLAND_INSTANCE_SIGNATURE).
3. Install the server in an MCP‑compatible client (e.g., Claude Desktop) by configuring the client to run the uv command with the appropriate arguments and environment variables.
4. Start the server locally for development with mcp dev server.py while Hyprland is running.

Key features of Hyprland MCP Server

• run_hyprctl_command: Execute arbitrary hyprctl commands.
• get_version: Retrieve Hyprland version and build information.
• list_monitors / list_workspaces / list_clients: Detailed listings of monitors, workspaces, and windows.
• list_devices: Show connected input devices.
• get_active_window: Information about the currently focused window.
• dispatch_command: Send Hyprland dispatch actions (e.g., workspace switch, kill mode).
• set_keyword / reload_config: Dynamically modify configuration keywords and reload the config file.
• enter_kill_mode: Enable kill mode for terminating windows via click.

Use cases of Hyprland MCP Server

• Voice‑controlled desktop: Let a voice assistant move windows, change workspaces, or adjust layouts using simple spoken commands.
• Chat‑bot integration: Enable a chat interface (e.g., Claude, ChatGPT) to manage the desktop environment for remote assistance.
• Automation scripts: Combine with other MCP tools to create complex workflows that react to system state (e.g., move a window when a specific monitor is connected).
• Testing & debugging: Programmatically query Hyprland state during development of extensions or custom compositors.

FAQ from the Hyprland MCP Server

Q: Do I need to run this on a specific OS? A: It is designed for Linux systems where Hyprland is installed.

Q: Which Python versions are supported? A: Python 3.10 or newer.

Q: Is the server stable for production use? A: The project is in beta and labeled experimental; it is suitable for testing and personal automation.

Q: How do I add new tools? A: Extend server.py by defining additional MCP tool functions that wrap the desired hyprctl commands.

Q: Can I run multiple instances? A: Each instance must be pointed at a distinct Hyprland instance via its HYPRLAND_INSTANCE_SIGNATURE.

Hyprland MCP Server

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

A lightweight, unofficial Model Context Protocol (MCP) server that exposes all the functionality of hyprctl—the command-line interface for the Hyprland Wayland compositor—to language models.

This server enables natural language interfaces to query and control Hyprland's window management, layouts, inputs, and more.

Note: This project is experimental and in beta.

🚀 Quick Start

1. Clone the repository

git clone https://github.com/stefanoamorelli/hyprmcp.git
cd hyprmcp

2. Grab your HYPRLAND_INSTANCE_SIGNATURE

echo $HYPRLAND_INSTANCE_SIGNATURE

3. Install the server in your MCP client

For example, in Claude Desktop, modify the ~/.config/Claude/claude_desktop_config.json file as follows:

"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>"
  }
},

🧰 Available Tools

Tool Name	Description
run_hyprctl_command	Executes arbitrary hyprctl commands.
get_version	Retrieves the Hyprland version and build info.
list_monitors	Lists all connected monitors and properties.
list_workspaces	Lists all active workspaces.
list_clients	Lists all windows and their properties.
list_devices	Lists all connected input devices.
get_active_window	Shows the currently active window details.
list_layers	Displays all layers in the compositor.
get_splash	Retrieves the current random splash message.
dispatch_command	Dispatches a command to Hyprland.
set_keyword	Dynamically sets a configuration keyword.
reload_config	Forces a reload of the Hyprland config file.
enter_kill_mode	Enables kill mode to terminate windows by click.

These tools allow language models to interact with Hyprland's features seamlessly.

💡 Example Usage

User Prompt: "Switch to workspace 2."

MCP Server Action: Executes hyprctl dispatch workspace 2.

User Prompt: "What is the current active window?"

MCP Server Action: Executes hyprctl activewindow -j and returns the details.

🛠️ Development

To run the server locally for development:

mcp dev server.py

Ensure that Hyprland is running and the necessary environment variables are set.

📚 References

• Hyprland Documentation
• Model Context Protocol
• Python MCP SDK

📜 License

MIT License © 2025 Stefano Amorelli