hyprmcp

What is hyprmcp?

hyprmcp is a lightweight, unofficial Model Context Protocol (MCP) server designed to expose the full functionality of hyprctl (the command-line interface for the Hyprland Wayland compositor) to large language models. This enables natural language interfaces to interact with and control Hyprland's window management, layouts, inputs, and more.

How to use hyprmcp?

To use hyprmcp, you first need to clone the repository and obtain your HYPRLAND_INSTANCE_SIGNATURE. Then, you install the server within your MCP client (e.g., Claude Desktop) by modifying its configuration file to include the hyprmcp server with the correct command, arguments, and environment variables, including the PYTHONPATH and your HYPRLAND_INSTANCE_SIGNATURE.

Key Features of hyprmcp

• hyprctl Integration: Exposes all hyprctl functionalities to language models.
• Natural Language Control: Enables interaction with Hyprland using natural language prompts.
• Comprehensive Toolset: Provides a variety of tools for managing Hyprland, including:
  • run_hyprctl_command: Executes arbitrary hyprctl commands.
  • get_version: Retrieves Hyprland version and build info.
  • list_monitors: Lists connected monitors.
  • list_workspaces: Lists active workspaces.
  • list_clients: Lists windows and their properties.
  • list_devices: Lists connected input devices.
  • get_active_window: Shows active window details.
  • list_layers: Displays compositor layers.
  • get_splash: Retrieves the current random splash message.
  • dispatch_command: Dispatches commands 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 for terminating windows by click.

Use Cases of hyprmcp

• Voice Control for Hyprland: Control your Hyprland desktop environment using voice commands through a language model.
• Automated Window Management: Create scripts or AI agents that can intelligently manage windows, workspaces, and layouts based on natural language instructions.
• Enhanced Productivity: Streamline workflows by using natural language to perform complex Hyprland operations.
• AI-powered Desktop Assistants: Develop desktop assistants that can understand and execute commands related to your Hyprland environment.

FAQ about hyprmcp

Q: Is hyprmcp stable? A: The project is currently experimental and in beta.

Q: What are the prerequisites for running hyprmcp? A: You need Hyprland running and the necessary environment variables set, including HYPRLAND_INSTANCE_SIGNATURE.

Q: Can I use hyprmcp with any MCP client? A: While the example shows Claude Desktop, it is designed to work with any MCP client that can integrate with external servers and set environment variables.

Q: How do I develop for hyprmcp? A: You can run the server locally for development using mcp dev server.py.

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