mcp-server-hyprland

An MCP (Model Context Protocol) server for interacting with Hyprland. This server allows AI clients to fetch Hyprland documentation directly from the official wiki, query the state of the active Hyprland session safely, and modify .conf files.

Features

• Fetch Documentation: Retrieve and read official Hyprland Markdown documentation from the repository.
• Query Hyprland State: Execute read-only hyprctl commands like monitors, workspaces, clients, activewindow, etc. Uses execFile for complete protection against command-injection.
• Manage Configuration: Safely read and append to ~/.config/hypr/*.conf files. Directory traversal protections are built-in.

Installation

You can run it directly with npx (make sure you have Node 18+ installed):

npx mcp-server-hyprland

If you are using an MCP client (such as Claude Desktop or Cline setup), add the following to your configuration:

Claude Desktop config

Edit ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "hyprland": {
      "command": "npx",
      "args": ["-y", "mcp-server-hyprland"]
    }
  }
}

Security

This tool was designed with security in mind since modifying configurations and executing hyprctl commands dynamically can be dangerous.

• hyprctl is executed using strict enumerations. Arbitrary shell arguments are strictly blocked.
• Config reading/updating paths are rigorously checked to ensure they physically resolve inside ~/.config/hypr and end with .conf. Attempted accesses to ../ or absolute paths outside of the config dir are denied.

Development

1. Clone this repository.
2. npm install
3. npm run build
4. node dist/index.js