HyprlandCAUTION
Community MCP server for hyprctl
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
[](LICENSE)
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",
"/hyprmcp/hyprmcp/server.py"
],
"env": {
"PYTHONPATH": "/hyprmcp",
"HYPRLAND_INSTANCE_SIGNATURE": ""
}
},🧰 Available Tools
a1a8bf2c47cbOBSERVED · 2026-10-08Exposed tools (12)
10 read · 1 write · 1 destructive. Blast radius: 1 tool can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
dispatch_command | read | Calls a dispatcher with an argument. |
enter_kill_mode | destructive | Enters kill mode to terminate an app by clicking on it. |
get_active_window | read | Returns the active window name. |
get_splash | read | Returns the current random splash. |
get_version | read | Returns the Hyprland version and build information. |
list_clients | read | Lists all windows with their properties. |
list_devices | read | Lists all connected input devices. |
list_layers | read | Lists all the layers. |
list_monitors | read | Lists all outputs with their properties. |
list_workspaces | read | Lists all workspaces with their properties. |
reload_config | read | Forces a reload of the config file. |
set_keyword | write | Sets a config keyword dynamically. |
Trust audit
CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | WARN |
| L1 | Static analysis of the code | PASS |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (1 observation(s))
- Network
- none-observed
- Shell
- none-observed
- Dependencies
- pinned
- Secrets in source
- none-found
Findings (2)
server.cpython-312.pyc
enter_kill_mode
Gates applied: no_behavioural_pass.
a1a8bf2c47cbfull audit observations/trust-audit/mcp-server/stefanoamorelli__hyprland.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-08 | a1a8bf2c47cb | CAUTION | B | 89 | first audit |
Questions
What is the Hyprland MCP server?
Community MCP server for hyprctl
What tools does Hyprland expose?
12 in total: 10 read-only, 1 that write, and 1 that can delete or overwrite (enter_kill_mode). Every one is listed on this page with its risk.
Is Hyprland safe to connect to an agent?
With care. The audit graded it B (89/100) and found 2 things worth knowing before you trust this server, listed below with the exact line each was found on. Separately from the audit: 1 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does Hyprland need?
No credential environment variables were found in its source, so it appears to need none.
How current is this page?
The grade is for one exact copy of the source (a1a8bf2c47cb), read on 2026-10-08. The repository is watched and re-audited when it changes.