Hyprland MCP server for AI agents

Hyprland MCP Server is a lightweight tool that exposes Hyprland's window management capabilities to language models through the Model Context Protocol (MCP). It enables natural language interfaces to control and query your Hyprland Wayland compositor, allowing for intuitive interaction with your desktop environment.

Installation

Prerequisites

A running Hyprland Wayland compositor
Python 3.10 or higher
Access to your Hyprland instance signature

Setup Steps

Clone the repository:

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

Get your Hyprland instance signature:
```
echo $HYPRLAND_INSTANCE_SIGNATURE
```
Make note of this value as you'll need it for configuration.

Configure your MCP client to use the server. For example, in Claude Desktop, modify the configuration file at ~/.config/Claude/claude_desktop_config.json:

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

Make sure to replace:

<global path of the repo> with the actual path to your cloned repository
<your-hyprland-instance-signature> with the value you obtained earlier

Usage

Available Tools

The server provides a variety of tools for interacting with Hyprland:

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

Example Interactions

You can use natural language to interact with Hyprland through your MCP-compatible model. For example:

To switch workspaces: "Switch to workspace 2"
The server will execute: hyprctl dispatch workspace 2
To get information: "What is the current active window?"
The server will execute: hyprctl activewindow -j and return the details
To modify settings: "Change my mouse sensitivity"
The server can use the appropriate commands to adjust these settings

Local Testing

To run the server locally for development purposes:

mcp dev server.py

Ensure that Hyprland is running and the necessary environment variables are set before executing this command.

Additional Resources

For more information, refer to:

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "hyprmcp" '{"command":"uv","args":["run","--with","mcp[cli]","--with","subprocess","mcp","run","hyprmcp/hyprmcp/server.py"],"env":{"PYTHONPATH":"hyprmcp","HYPRLAND_INSTANCE_SIGNATURE":"${HYPRLAND_INSTANCE_SIGNATURE}"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "hyprmcp": {
            "command": "uv",
            "args": [
                "run",
                "--with",
                "mcp[cli]",
                "--with",
                "subprocess",
                "mcp",
                "run",
                "hyprmcp/hyprmcp/server.py"
            ],
            "env": {
                "PYTHONPATH": "hyprmcp",
                "HYPRLAND_INSTANCE_SIGNATURE": "${HYPRLAND_INSTANCE_SIGNATURE}"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "hyprmcp": {
            "command": "uv",
            "args": [
                "run",
                "--with",
                "mcp[cli]",
                "--with",
                "subprocess",
                "mcp",
                "run",
                "hyprmcp/hyprmcp/server.py"
            ],
            "env": {
                "PYTHONPATH": "hyprmcp",
                "HYPRLAND_INSTANCE_SIGNATURE": "${HYPRLAND_INSTANCE_SIGNATURE}"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect