Skip to main content
Glama
Sign In
hyprland-mcp

hyprland-mcp

by Lord93jdiso
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Hyprland MCP Server

MCP (Model Context Protocol) server for controlling Hyprland via AI agents.

Talk to Hyprland over hyprctl — query state, dispatch commands, change settings, edit config.

Requires running inside a Hyprland session.

Tools

Query:

Tool

What it does

hyprctl_raw

Run any hyprctl command

get_monitors

List monitors

get_workspaces

List workspaces

get_clients

List windows

get_active_window

Focused window details

get_devices

Input devices

get_binds

Keybinds

get_option

Any config option value

get_version

Hyprland version

get_layers

Compositor layers

Actions:

Tool

What it does

dispatch

Run a dispatcher (workspace, exec, kill, floating...)

set_keyword

Change a setting on the fly

reload_config

Reload hyprland.conf

notify

Send notification

kill_window

Kill-window mode

Config:

Tool

What it does

read_config

Read hyprland.conf

get_config_section

Parse a specific section

set_config_value

Edit a value + reload

add_config_line

Append a line + reload

Related MCP server: astra-linux-agent

Install

pip install mcp
python mcp_server.py

opencode.jsonc

{
  "hyprland-mcp": {
    "type": "local",
    "command": ["python", "-m", "mcp_server"],
    "env": { "PYTHONPATH": "/path/to/hyprland-mcp" },
    "enabled": true
  }
}

Wiki

https://wiki.hypr.land/ — embedded as knowledge://hyprland-wiki resource.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    This server cannot be deployed

    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • astra-linux-agent

      novique-ai
      A
      license
      Not graded
      quality
      C
      maintenance
      Enables an AI agent to see and control a Linux desktop via Wayland/Hyprland, providing screenshots, structured desktop state, pointer/keyboard input, semantic window/workspace tools, and a policy engine for safe execution.
      Apache 2.0

    • hypr-mcp

      tuan-cre
      A
      license
      B
      quality
      B
      maintenance
      Enables AI assistants to automate Hyprland desktop environments through screenshots, mouse/keyboard input, window management, workspaces, clipboard, app launching, and OCR.
      27
      1
      MIT

    • hyprcu

      angusforbes
      A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to control Hyprland desktops via MCP, including pointer/keyboard input, screenshots, launching apps, and natural-language window targeting using a local decision model.
      14
      1
      MIT