hyprland-mcp

Instructions

Implementation Reference

• hyprland_mcp/server.py:71-94 (handler)

  The list_windows tool handler function in hyprland_mcp/server.py. It retrieves window data via hyprctl and filters them by workspace or monitor if provided.

  @mcp.tool()
  async def list_windows(workspace: int | None = None, monitor: str | None = None) -> str:
      """List all open windows with class, title, size, and position.
  
      Args:
          workspace: Filter to a specific workspace number
          monitor: Filter to a specific monitor name
      """
      clients = await hyprctl.query("clients")
      if workspace is not None:
          clients = [c for c in clients if c["workspace"]["id"] == workspace]
      if monitor is not None:
          clients = [c for c in clients if c["monitor"] == monitor]
      if not clients:
          return "No windows found matching the filter."
      lines = []
      for c in clients:
          focused = " [focused]" if c.get("focusHistoryID") == 0 else ""
          lines.append(
              f"- [{c['class']}] \"{c['title']}\" — "
              f"{c['size'][0]}x{c['size'][1]} at ({c['at'][0]},{c['at'][1]}), "
              f"workspace {c['workspace']['name']}{focused}"
          )
      return "\n".join(lines)