List all Quickshell documentation versions currently published on quickshell.org, newest first, and report which one is latest. Use this before fetching a page if you're unsure which version to use. Set refresh=True to bypass the in-process cache.

Fetch the Quickshell 'About' page (https://quickshell.org/about/) as Markdown. Use this for high-level questions like what Quickshell is, who maintains it, and how it's licensed.

Fetch the Quickshell changelog (https://quickshell.org/changelog/) as Markdown. Use this to answer 'what's new / what changed' questions.

List the Usage Guide pages available for a given doc version (e.g. install-setup, introduction, size-position, qml-language, advanced, faq). Defaults to the latest version if none given. Set refresh=True to bypass the in-process cache.

Fetch one Usage Guide page as Markdown, e.g. slug='introduction' or slug='qml-language'. Call quickshell_list_guide_pages first if you don't know the exact slug. Defaults to the latest doc version.

List Quickshell QML types, optionally filtered to one namespace (e.g. 'Quickshell.Hyprland', 'Quickshell.Io', 'Quickshell.Services.Pipewire'). Call with no namespace to see every namespace and its types. Defaults to the latest doc version. Set refresh=True to bypass the in-process cache.

Fetch the documentation page for one QML type as Markdown, e.g. type_name='PanelWindow', namespace='Quickshell', or type_name='HyprlandMonitor', namespace='Quickshell.Hyprland'. Call quickshell_list_types first if you're unsure of the exact namespace or type name (they are case-sensitive). Defaults to the latest doc version.

Search Quickshell type names, namespaces, and guide page slugs for a substring match (case-insensitive). ALWAYS call this before writing any QML that references a Quickshell type or property from memory; never guess property/type names, verify them here first.

Use this whenever a request mentions a desktop-shell feature and you don't already know the exact Quickshell type name, e.g.:

• "battery" / "power" / "upower" -> search 'battery' or 'power' (UPower, UPowerDevice)

• "volume" / "audio" / "mixer" -> search 'audio' or 'volume' (Pipewire, PwNode)

• "tray" / "system tray" -> search 'tray' (SystemTray, SystemTrayItem)

• "workspaces" / "monitor" -> search 'monitor' or 'workspace' (HyprlandMonitor, HyprlandWorkspace, I3Monitor)

• "notifications" -> search 'notification' (Notification, NotificationServer)

• "network" / "wifi" -> search 'wifi' or 'network' (WifiDevice, Network)

• "bluetooth" -> search 'bluetooth' (Bluetooth, BluetoothDevice)

• "clock" / "date" / "time" -> search 'clock' (SystemClock)

For concept/how-to questions where the answer is prose rather than a type name ("where is IPC documented?", "how do anchors work?"), pass include_content=True; this also full-text-searches the guide-page bodies. Pass include_type_pages=True to also deep-search the ~200 type reference pages for property/method/signal text (slower: first call fetches every type page once, then it's cached).

Returns matches with enough info to call quickshell_get_type or quickshell_get_guide_page directly. Namespace and type matches are reported separately so a namespace hit doesn't flood the results with all of its types. Defaults to the latest doc version. Set refresh=True to bypass the in-process cache.

List QML types documented on doc.qt.io for QtQuick and its sibling modules (Controls, Layouts, Effects, Shapes, ...), discovered from the QtQuick module page. Use this for Qt base types like Rectangle, Text, MouseArea, Timer, or RowLayout that Quickshell configs import but the Quickshell docs don't describe themselves. For Quickshell-specific types use quickshell_list_types instead. qt_version pins a minor (e.g. '6.8', '6.7') instead of the newest release. Set refresh=True to bypass the in-process cache.

Fetch one Qt type's reference page from doc.qt.io as Markdown, e.g. Rectangle, Text, MouseArea, Timer, Item, RowLayout, or a value type like color or vector3d. Use this when a Quickshell config imports QtQuick / QtQuick.Controls / QtQuick.Layouts types and you need their properties, signals, or syntax. Pass module (e.g. 'qtquick', 'qtquick-controls') to disambiguate names that exist in several modules. qt_version pins a minor (e.g. '6.8') to match your installed Qt instead of the newest.

List files and folders in the official Quickshell examples repo (real-world sample shell/bar/widget configs written by the Quickshell authors). Call with no path to list the root, then drill into a folder using its path. Pair with quickshell_get_example to read a file's contents.

Read one file from the official Quickshell examples repo verbatim (QML configs, READMEs). Get valid paths from quickshell_list_examples. Prefer these maintained examples over writing a shell config from memory.

Search real-world Quickshell shells (Caelestia, Noctalia) for implementations: 'find a bar implementation', 'find a control center example', 'find Quickshell IPC usage', 'find multi-monitor implementation', 'find workspace widget', 'find notification/OSD/launcher implementation', 'find lock screen', 'find wallpaper handling', 'find Quickshell animations', 'find service patterns', 'find reusable QML components', 'find Hyprland/Niri integration', 'find volume/audio implementation', 'find wifi/network implementation', 'find bluetooth', 'find brightness', 'find battery implementation', 'find media controls'. Restrict to one shell with source='caelestia' or source='noctalia'; to compare approaches, call once per shell. These are practical references, NOT API docs: verify API surface with quickshell_search/ quickshell_get_type. Get file contents via quickshell_get_implementation.

Read a QML file from the Caelestia or Noctalia shells (get paths from quickshell_search_implementations). Pass find='osd' / find='workspace' / find='ipc' etc. to jump to the most relevant section instead of pulling the whole large file. This is a real-world implementation reference, NOT official documentation: when it disagrees with quickshell.org or doc.qt.io, trust the docs.

Report session usage stats for this MCP server: per-tool call counts, network fetches vs cache hits, and process uptime. Use this to check how much the server has been consulted and how much it hit the live site vs its 30-minute cache.