by stefanoamorelli
Enables natural language interfaces to query and control Hyprland's window management, layouts, inputs, and more via hyprctl.
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.
echo $HYPRLAND_INSTANCE_SIGNATURE
).mcp dev server.py
) ensuring Hyprland is running and the environment variable is set.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.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.
git clone https://github.com/stefanoamorelli/hyprmcp.git
cd hyprmcp
HYPRLAND_INSTANCE_SIGNATURE
echo $HYPRLAND_INSTANCE_SIGNATURE
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>"
}
},
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.
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.
To run the server locally for development:
mcp dev server.py
Ensure that Hyprland is running and the necessary environment variables are set.
MIT License © 2025 Stefano Amorelli
Please log in to share your review and rating for this MCP.
Discover more MCP servers with similar functionality and use cases
by Skyvern-AI
Skyvern automates browser-based workflows using LLMs and computer vision, offering a robust solution for repetitive online tasks.
by PipedreamHQ
Connect APIs quickly, run event‑driven automations, and execute custom code in Node.js, Python, Go, or Bash on a hosted platform.
by czlonkowski
Provides AI assistants with structured access to n8n node documentation, properties, and operations, enabling automated workflow creation, validation, and management.
by executeautomation
mcp-playwright is a Model Context Protocol (MCP) server that enables large language models (LLMs) to perform browser automation and web scraping tasks using Playwright.
by browserbase
Provides cloud browser automation capabilities for LLMs, enabling web navigation, interaction, screenshot capture, and data extraction through Browserbase and Stagehand.
by haris-musa
excel-mcp-server is a Python-based Model Context Protocol (MCP) server that enables AI agents to programmatically create, read, and modify Excel files without requiring Microsoft Excel to be installed.
by mobile-next
Mobile-mcp is a Model Context Protocol (MCP) server designed for scalable mobile automation, app scraping, and development across iOS and Android devices, including physical devices, simulators, and emulators.
by anaisbetts
mcp-installer is an MCP server designed to automate the installation of other MCP servers, simplifying the process for users.
by leonardsellem
An MCP server that enables AI assistants to interact with n8n workflows through natural language.