hyprmcp

Community MCP server for hyprctl

20 stars PythonServers & Infrastructure Updated Oct 15, 2025

Documentation

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

bash

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

2. Grab your `HYPRLAND_INSTANCE_SIGNATURE`

bash

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:

json

"Hyperland MCP Server": {
  "command": "uv",
  "args": [
    "run",
    "--with",
    "mcp[cli]",
    "--with",
    "subprocess",
    "mcp",
    "run",
   "/hyprmcp/hyprmcp/server.py"
  ],
  "env": {
    "PYTHONPATH": "/hyprmcp",
    "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:

bash

mcp dev server.py

Ensure that Hyprland is running and the necessary environment variables are set.

📚 References

📜 License

Frequently asked questions

What is hyprmcp?

hyprmcp is Community MCP server for hyprctl

How do I install hyprmcp?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is hyprmcp open source?

Yes — it is hosted on GitHub at https://github.com/stefanoamorelli/hyprmcp and has 20 stars.

Related MCP tools

damn-vulnerable-mcp-server

Damn Vulnerable MCP Server Python-based implementation. Trusted by 1200+ developers. Trusted by 1200+ developers. Trusted by 1200+ developers.

1,209 Python

mysql_mcp_server

A Model Context Protocol (MCP) server that enables secure interaction with MySQL databases Python-based implementation. Trusted by 900+ developers.

964 Python

aimcpmodel-context-protocol+1

supabase-mcp-server

Query MCP enables end-to-end management of Supabase via chat interface: read & write query executions, management API support, automatic migration versioning...

805 Python

cursormodel-context-protocolsupabase+1