Hyprmcp

🚀 Hyprland MCP Server

A lightweight, unofficial Model Context Protocol (MCP) server that exposes all the functionalities of hyprctl (the command-line interface for Hyprland Wayland compositor), enabling language models to query and control Hyprland's window management, layout, input, etc.

This server allows natural language interfaces to query and control Hyprland's window management, layout, input, and more.

⚠️ Important Note

This project is experimental and in the testing phase.

🚀 Quick Start

1. Clone the repository

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

2. Get your HYPRLAND_INSTANCE_SIGNATURE

echo $HYPRLAND_INSTANCE_SIGNATURE

3. Install the server in the 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>"
  }
},

✨ Features

🧰 Available Tools

💻 Usage Examples

Basic Usage

# Query monitor information
mcp run hyperland_mcp_server.list_monitors

# Query window information
mcp run hyperland_mcp_server.get_active_window

# Query workspace information
mcp run hyperland_mcp_server.list_workspaces

🔧 Technical Details

🛠️ Development Instructions

# Run the server
python3 -m hyperland_mcp_server

📄 License

• MCP Protocol
• Hyprland Repository
• License