# Hyprmcp

> Community MCP server for hyprctl

- **Type:** MCP server
- **Install:** `agentstack add mcp-stefanoamorelli-hyprmcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [stefanoamorelli](https://agentstack.voostack.com/s/stefanoamorelli)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [stefanoamorelli](https://github.com/stefanoamorelli)
- **Source:** https://github.com/stefanoamorelli/hyprmcp

## Install

```sh
agentstack add mcp-stefanoamorelli-hyprmcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Hyprland MCP Server

[](LICENSE)

https://github.com/user-attachments/assets/b4fc1d26-ec04-451a-b7c9-7f87b44d9c9e

A lightweight, unofficial [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol) server that exposes all the functionality of `hyprctl`—the command-line interface for the [Hyprland](https://wiki.hyprland.org/) 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

- [Hyprland Documentation](https://wiki.hyprland.org/)
- [Model Context Protocol](https://github.com/modelcontextprotocol)
- [Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk)

## 📜 License

[MIT License](LICENSE) © 2025 Stefano Amorelli

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [stefanoamorelli](https://github.com/stefanoamorelli)
- **Source:** [stefanoamorelli/hyprmcp](https://github.com/stefanoamorelli/hyprmcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-stefanoamorelli-hyprmcp
- Seller: https://agentstack.voostack.com/s/stefanoamorelli
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.