Hyprland MCP Server

What is Hyprland MCP Server about?

Provides a lightweight, unofficial Model Context Protocol server that exposes the full functionality of hyprctl, the command‑line tool for the Hyprland Wayland compositor, to language models. By bridging hyprctl commands with natural language, users can interact with their window manager through AI assistants.

How to use Hyprland MCP Server?

Clone the repository and navigate to the project directory.
Obtain the Hyprland instance signature (echo $HYPRLAND_INSTANCE_SIGNATURE).
Run the server (e.g., mcp dev server.py) ensuring Hyprland is running and the environment variable is set.
In an MCP‑compatible client (such as Claude Desktop), configure the server command and environment variables as shown in the README. The client can then invoke the exposed tools via natural language prompts.

Key features of Hyprland MCP Server

run_hyprctl_command: Execute any arbitrary hyprctl command.
get_version: Retrieve Hyprland version and build information.
list_monitors, list_workspaces, list_clients, list_devices: Detailed listings of monitors, workspaces, windows, and input devices.
get_active_window: Show the currently focused window.
dispatch_command: Send a dispatch to Hyprland (e.g., change workspace, move windows).
set_keyword, reload_config: Dynamically modify configuration and reload it.
enter_kill_mode: Enable click‑to‑kill mode for windows.
All tools are accessible through MCP, allowing AI agents to control the compositor seamlessly.

Use cases of Hyprland MCP Server

Voice‑controlled desktop: Users can speak commands like “Switch to workspace 3” or “Move the active window to monitor 2”.
AI‑driven automation: Scripts powered by language models can arrange windows, adjust layouts, or react to system events without manual scripting.
Assistive technology: People with limited mobility can manage their Linux desktop through natural language.
Testing & debugging: Developers can programmatically query Hyprland state and simulate user actions for regression tests.

FAQ from the Hyprland MCP Server

Q: Is the server stable for production use? A: The project is currently experimental and in beta; it is recommended for personal or testing environments.

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

Q: Do I need any additional dependencies? A: Apart from the standard Python environment, you need uv (or another Python runner) and a running Hyprland session with the HYPRLAND_INSTANCE_SIGNATURE environment variable set.

Q: Can I add custom hyprctl commands? A: Yes, the run_hyprctl_command tool allows execution of any arbitrary hyprctl command.

Q: How do I integrate the server with an MCP client? A: Configure the client to run the server script (e.g., via uv run), set PYTHONPATH to the repository root, and provide the instance signature in the environment.

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.

Hyprland MCP Server