home / mcp / hyprland mcp server

Hyprland MCP Server

Provides MCP access to Hyprland via an API that exposes hyprctl-like commands for querying and controlling windows, layouts, and inputs.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "stefanoamorelli-hyprmcp": {
      "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>"
      }
    }
  }
}

You can control Hyprland from language models via a lightweight MCP server that exposes the full functionality of the Hyprctl command-line interface. This lets you query window layouts, workspaces, inputs, and other Hyprland features through natural language interactions, enabling automation and smarter UI management.

How to use

You connect to the Hyprland MCP Server from your MCP client and use the available tools to query state, switch workspaces, list windows, or dispatch commands to Hyprland. Start by ensuring Hyprland is running and the server is accessible through your MCP client configuration. Then issue natural language prompts that map to the provided tools, such as asking for the current active window, switching to a specific workspace, or querying monitor layouts.

How to install

Prerequisites: Ensure you have a compatible MCP client and a Python environment ready. The server runs as a standalone Python process and relies on a local command interface to Hyprland.

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

Additional notes

The server exposes a set of tools that you can invoke from your MCP client to interact with Hyprland. Ensure you provide the HYPRLAND_INSTANCE_SIGNATURE environment variable so the server can communicate with your Hyprland instance. If you modify your local setup, update the PATH or PYTHONPATH accordingly to ensure the server can locate its Python modules.

Available tools

run_hyprctl_command

Executes arbitrary hyprctl commands via the MCP server.

get_version

Retrieves 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 details of the currently active window.

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.