HY
Developer Tools

Hyprmcp Lightweight MCP Server for Hyprland

Install Hyprmcp, a lightweight MCP server for Hyprland by Stefano Amorelli, to enable efficient compositor messaging and plugin integration.

View on GitHub
Quick Install
npx -y @stefanoamorelli/hyprmcp

Overview

Hyprmcp is a lightweight MCP (Model Context Protocol) server designed to bridge Hyprland with external plugins and automation tools. It exposes compositor events and accepts commands over a small IPC surface so scripts, status bars, and language runtimes can interact with Hyprland without embedding Wayland or compositor internals. The project is focused on minimal dependencies, low latency, and a simple message-based protocol that is easy to consume from many languages.

For plugin authors and automation engineers, hyprmcp reduces the friction of integrating with Hyprland: instead of polling or shelling out to the compositor CLI, clients can subscribe to events, query state, and push commands through a single, always-on IPC endpoint. This makes it well suited for dynamic status bars, window managers, hotkey handlers, and diagnostics tooling.

Features

  • Minimal, low-overhead MCP server for Hyprland
  • IPC-based API (Unix domain socket) for language-agnostic clients
  • Publish/subscribe event model for compositor events (workspaces, windows, monitors, etc.)
  • Simple request/response command handling for actions and queries
  • Small binary with zero-runtime GUI dependencies — easy to run as a user service
  • Examples and client-friendly protocol to accelerate plugin development

Installation / Configuration

Clone and build from the repository, or use prebuilt releases if available.

Build from source (example using Cargo if the project is Rust-based):

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

# build release (if the repository uses Cargo)
cargo build --release

# install binary into ~/.local/bin (adjust path as necessary)
install -Dm755 target/release/hyprmcp ~/.local/bin/hyprmcp

Run the server directly:

# start with a socket path
hyprmcp --socket /run/user/1000/hyprmcp.sock

Recommended systemd user service unit (place at ~/.config/systemd/user/hyprmcp.service):

[Unit]
Description=Hyprmcp MCP server for Hyprland
After=graphical-session.target

[Service]
Type=simple
ExecStart=/home/%u/.local/bin/hyprmcp --socket /run/user/%u/hyprmcp.sock
Restart=on-failure
Environment=RUST_LOG=info

[Install]
WantedBy=default.target

Enable and start:

systemctl --user enable --now hyprmcp.service

Configuration

  • hyprmcp supports a small set of runtime options (socket path, logging level, allowed clients). Pass them as CLI flags or via environment variables where supported.
  • By default, choose a per-user socket path such as /run/user/$(id -u)/hyprmcp.sock to integrate cleanly with session services.

Available Resources

  • Repository & issue tracker: https://github.com/stefanoamorelli/hyprmcp
  • Releases: check the repository Releases tab for prebuilt binaries
  • Examples: look in the examples/ directory in the repo for client snippets and integration samples
  • Protocol docs: consult the repo README or docs directory for the MCP message format (JSON-based or line-delimited messages)

If you are building clients:

  • Any language that can talk to Unix domain sockets (Python, Node.js, Go, Rust, shell via socat) can interact with hyprmcp
  • Use the examples to copy the subscription and request/response patterns

Use Cases

  1. Status bars and widgets

    • Subscribe to workspace and window events and redraw UI elements only when needed (e.g., active workspace change).
    • Example: a status bar subscribes to “workspace” events and receives a compact event payload whenever focus or workspace names change.

  2. Automation scripts

    • Trigger actions on monitor plug/unplug or specific window events. For example, automatically move a freshly-opened window to a particular workspace or monitor based on application class.

  3. Hotkey handlers and macros

    • Implement hotkey daemons that send commands to Hyprland through hyprmcp rather than shelling out to the compositor CLI. This reduces latency and simplifies state handling.

  4. Diagnostics and logging

    • Stream compositor events to files or remote collectors for debugging performance regressions or reproducing UI bugs.

  5. Cross-language plugin ecosystem

    • Language-agnostic protocol enables community plugins in Python, Node.js, Go, or Lua without relying on Hyprland’s internal APIs.

Quick example: Python client (connect to Unix socket)

import socket, json
Tags:developer-tools