Quickshell MCP server

Read from the package source without running it. The installed server may list more.

• quickshell_about

  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.

• quickshell_api_diff

  Compare two Quickshell versions and report added, removed, renamed, and deprecated APIs, each with provenance (changelog and type-page URLs). Read-only.

• quickshell_api_graph

  Build a documented API dependency graph for a type: its declared properties (with their types) and its documented base type. Only documented relationships are included — no speculative edges. Read-only.

• quickshell_apply_patchwrite action

  Apply a previously generated edit set to a Quickshell project, but only when explicitly requested. This is a mutating operation.

• quickshell_assertwrite action

  Run a single reusable assertion primitive against a managed runtime session: object_exists, property_equals, property_contains, property_matches, visible, enabled, text_matches, window_exists.

• quickshell_best_practice

  Return evidence-backed implementation guidance ranked by authority: official docs > official examples > real-world shells. Documented behavior is separated from community convention. Read-only.

• quickshell_binding_inspect

  Inspect a binding on a managed runtime object: current live value, likely source expression (from the project QML), and files that reference it. Read-only.

• quickshell_build_feature

  Build a feature end-to-end: analyze the project, research the APIs, generate a verified component, validate it, and optionally apply a permitted edit set. Returns the full staged plan. Read-only unless apply=True and an explicit edit set is given (then mutating).

• quickshell_changelog

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

• quickshell_check_compatibility

  Check whether a Quickshell API, QML property/method/signal, type, or code snippet is compatible with a specific Quickshell version. Use this before targeting an older release, e.g. 'is PanelWindow.exclusiveZone available in v0.2.0?', 'which version introduced SomeType?', 'does this QML config work on v0.3.0?', 'was Quickshell.shellRoot renamed?'.

• quickshell_coding_assistant

  High-level Quickshell development assistant for AI coding agents.

• quickshell_dbus_services

  List user-session D-Bus services read-only via ``busctl``. Discovery only — method invocation is never performed. Read-only.

• quickshell_debug

  Debug a failure end-to-end: explain the error from the docs, then correlate live runtime evidence (errors, diagnosis, trace, binding) when a session id is given. Inferred causes are kept separate from observed evidence. Read-only.

• quickshell_engineerwrite action

  Run the full engineering loop end-to-end: build → test → debug → optimize → verify, composing the agent tools with per-stage isolation so one failing stage never sinks the rest. Pass tests= a machine- readable suite to enable the test stage; the loop is otherwise read-only. Returns every stage's result plus the flattened plan.

• quickshell_explain_error

  Explain a Quickshell/QML error and suggest a fix, grounded in the actual documentation. Pass the error message; optionally include QML code, the filename, line number, component/type name, or Quickshell version for a more precise diagnosis.

• quickshell_find_pattern

  Find real implementations of a FEATURE you want to build, described in plain words instead of exact type names: 'Hyprland workspace indicator', 'macOS-style control center', 'volume OSD', 'system tray', 'animated popup', 'floating notification', 'top bar with workspaces', 'launcher like Spotlight', 'power menu'. Searches Caelestia, Noctalia, and end-4's dots-hyprland (real-world shells) plus the o

• quickshell_generate_component

  Generate a minimal, source-grounded Quickshell QML component from a plain-language description, e.g. 'Create a Hyprland workspace indicator', 'animated volume OSD', 'top bar with workspaces, clock and system tray', 'popup control center', or 'notification popup'.

• quickshell_generate_panel

  Generate high-level panel scaffolding for a bar, OSD, launcher, dashboard, control center, or notification panel. This is scaffolding, not a full design generator: it reuses the component generator and project style detection, and outputs minimal, valid, extendable QML. Pass project= to align version, compositor, and conventions with the project.

• quickshell_generate_service

  Generate a generic, architecture-neutral Quickshell service abstraction for a common application concern. The first version returns a verified service skeleton with declared imports and a placeholder service object you can extend; it is deliberately generic rather than a giant library of service templates. No nonexistent Quickshell APIs are emitted. Pass project= to align the target version and co

• quickshell_get_example

  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.

• quickshell_get_guide_page

  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.

• quickshell_get_implementation

  Read a QML file from the Caelestia, Noctalia, or dots-hyprland 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.

• quickshell_get_qt_type

  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 mod

• quickshell_get_type

  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.

• quickshell_hyprland_info

  Inspect the Hyprland compositor read-only: monitors, workspaces, the active workspace, and clients, via ``hyprctl -j``. Returns an explanatory note when Hyprland/hyprctl is unavailable. Never modifies the compositor.

• quickshell_list_examples

  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.

• quickshell_list_guide_pages

  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.

• quickshell_list_qt_types

  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 pin

• quickshell_list_types

  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.

• quickshell_list_versions

  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.

• quickshell_migrate

  Migrate Quickshell/QML code from one Quickshell version to another: 'migrate this config from v0.2.0 to v0.3.0', 'what do I need to change to upgrade to the latest Quickshell?', 'is my config still valid after the upgrade?'. Analyzes the code (or a single API/type) against both versions and reports every removed, renamed, deprecated, or changed API, plus breaking changes from the changelog, each w

• quickshell_migrate_project

  Migrate a whole project between Quickshell versions: summarize the API delta, run the per-file migration engine, and report confirmed breaking issues with sources. Read-only.

• quickshell_nix_diagnostics

  Detect the Nix infrastructure of a Quickshell project: flake.nix presence, devShells, nixpkgs inputs, and whether the flake is locked. File-based detection only (no nix evaluation). Falls back to the system package manager when no flake.nix is present. Read-only.

• quickshell_optimize

  Optimize a project: profile a live session (when given) and run static component/binding/timer analysis plus a correlated diagnosis. Cost is never attributed without evidence. Read-only.

• quickshell_pattern_compare

  Compare how the indexed real-world shells (Caelestia, Noctalia, dots-hyprland) solve the same problem: per-project matches and source locations. Presents differences for comparison; never declares one implementation correct. Read-only.

• quickshell_performance_diagnose

  Correlate static project evidence (bindings, timers, object tree) into prioritized performance hypotheses with evidence and confidence. Never modifies source. Read-only.

• quickshell_pipewire_info

  Inspect PipeWire read-only: sinks, sources, and device identity via ``pw-cli``. Returns a note when PipeWire/pw-cli is unavailable. Never changes device state.

• quickshell_profile

  Measure runtime characteristics of a managed session: CPU usage, memory (RSS), and sample duration via bounded /proc sampling. Reports methodology and limitations. Read-only.

• quickshell_profile_bindings

  Identify high-frequency or broad property bindings statically (potential re-evaluation chains). Static only; re-evaluation frequency needs runtime instrumentation. Read-only.

• quickshell_profile_component

  Identify components with potential performance concerns from static evidence: timer/animation counts and layout bindings. Never attributes cost without evidence. Read-only.

• quickshell_profile_deletewrite action

  Delete a saved runtime profile from the in-memory registry by name. Mutates the profile registry only.

• quickshell_profile_export

  Export a saved runtime profile as a JSON-serializable dict (with its schema version), for backup or sharing between servers. Read-only.

• quickshell_profile_get

  Get a single saved runtime profile by name, with its full launch configuration and schema version. Read-only.

• quickshell_profile_import

  Import a runtime profile into the registry from a dict (e.g. the output of quickshell_profile_export). A payload with a newer schema version than this server supports is refused. Mutates the profile registry only.

• quickshell_profile_list

  List all saved runtime profiles with summary info: name, project root, entrypoint, compositor, and schema version. Read-only.

• quickshell_profile_object_tree

  Report object-tree statistics from static QML structure: total objects, repeated component patterns, and nesting depth. Useful for optimization; large trees are not automatically bad. Read-only.

• quickshell_profile_save

  Save a named runtime launch profile in this server's in-memory registry. Profiles are pure data (never launched by saving); combine them with quickshell_runtime_start. Mutates the profile registry only.

• quickshell_profile_timers

  Find timers with potentially suspicious configuration (very short intervals, repeat disabled). Frequent timers are not labeled bugs by themselves. Read-only.

• quickshell_project_analyze

  Inspect a Quickshell project and produce a structured project overview containing, where detectable: Quickshell version, Qt version, entrypoints, QML files, JS files, imports, Quickshell modules, components, services, compositor integrations, runtime dependencies, and project configuration.

• quickshell_project_architecture

  Produce evidence-backed architecture recommendations for a project: confirmed cycles, unresolved references, and docs-grounded guidance. Every recommendation cites its evidence and basis. Read-only.

• quickshell_project_compatibility

  Analyze a whole project's Quickshell API compatibility against a target version: unavailable, deprecated, or changed APIs with affected files and concrete locations.

• quickshell_project_config

  Detect a Quickshell project's configuration conventions: entrypoints, configuration files, environment variables, structural conventions, and runtime hints. Inferred values include confidence levels; directly observed values carry high confidence.

• quickshell_project_dependencies

  Detect a Quickshell project's dependencies from source and configuration, without executing anything.

• quickshell_project_find

  Project-aware search: find where a concept, API, type, or property is used in a Quickshell project. Supports both exact textual matching and semantic/project-aware matching (type names, import modules).

• quickshell_project_lintwrite action

  Run quality-oriented lint checks across a Quickshell project.

• quickshell_project_map

  Build a machine-readable project graph showing relationships between QML components, imports, service dependencies, entrypoints, and module dependencies. Relies on reliable static relationships.

• quickshell_project_memory

  Project memory: explicit, evidence-backed notes about a project (13.1). action= is one of save (store a keyed entry with evidence), list (summarize), get (one entry), clear (one key), or reset (all). Memory is session-scoped, inspectable, and resettable. Read-only except the registry mutations it performs.

• quickshell_project_migrate

  Analyze a whole Quickshell project for what must change to move from one Quickshell version to another: breaking and deprecated APIs, required changes, and a machine-readable proposed-edit list.

• quickshell_project_validatewrite action

  Run the static QML validator across an entire Quickshell project and aggregate syntax errors, import problems, type problems, property and signal issues, version mismatches, and deprecated or unavailable APIs.

• quickshell_provenance

  Return provenance for knowledge results: source, version, URL, and authority level (docs > examples > real-world), so higher-level results can cite them. Read-only.

• quickshell_refactor

  Propose a safe refactoring (rename component, property, or reference) across a Quickshell project: rename an identifier everywhere it appears as a whole token. Returns structured edits plus a unified diff. Never writes files — apply the edits with quickshell_apply_patch when you are ready.

• quickshell_regression_detect

  Detect regressions by comparing the current state against a baseline: validation of every QML file plus an optional screenshot comparison. Only confirmed changes are reported; absent baselines are surfaced, not fabricated. Read-only.

• quickshell_reload

  Reload a managed runtime session, preserving session tracking. Reuses the lifecycle implementation; cleans up after failed reloads. Never touches production Quickshell processes. Mutating.

• quickshell_root_cause

  Correlate evidence into a root cause, separating inferred hypotheses from observed evidence. Combines static doc-grounded explanation with live runtime diagnosis; never fabricates a cause without evidence. Read-only.

• quickshell_runtime_dependencies

  Detect what a Quickshell project needs at runtime, statically and safely: QML types (Process, IpcHandler, ...), config keywords, imports, compositor, services, and which system binaries are on PATH. Nothing is executed. Read-only.

• quickshell_runtime_diagnose

  Diagnose a managed runtime session: combine runtime logs, errors, project context, and version info into a probable root cause with confidence. Never fabricates a cause when evidence is insufficient. Read-only.

• quickshell_runtime_errors

  Extract and normalize common Quickshell/QML runtime problems from a session's stderr: import failures, undefined properties, type mismatches, binding loops, component load failures, JS exceptions, and signal/method errors. Original error text is preserved. Read-only.

• quickshell_runtime_logs

  Return structured logs from a runtime session with optional filtering by stream (stdout/stderr), text, and a bounded limit. Read-only.

• quickshell_runtime_ping

  Lightweight readiness/health check for a runtime session.

• quickshell_runtime_reset

  Reset a managed runtime session to a clean state.

• quickshell_runtime_start

  Start a managed, isolated Quickshell runtime session for a project.

• quickshell_runtime_status

  Return structured status for a runtime session: session id, running state, PID, startup duration, exit code, and profile identity. Read-only.

• quickshell_runtime_stop

  Stop a managed runtime session safely (SIGTERM, then SIGKILL on timeout).

• quickshell_screenshot

  Capture a bounded screenshot of a managed Quickshell runtime session.

• quickshell_screenshot_diff

  Compare two runtime screenshots with ImageMagick ``compare``.

• quickshell_screenshot_region

  Capture a region-based screenshot of a managed runtime, preferring an object-derived region over manual coordinates. Read-only; requires grim.

• quickshell_search

  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.

• quickshell_search_all

  Search ALL sources at once with one natural-language query: Quickshell docs (type names, guide pages), Qt/QML types on doc.qt.io, official example configs, and real-world implementations (Caelestia, Noctalia, and end-4's dots-hyprland). Results come back grouped by source, most relevant group first; every entry carries a relevance score, a why-it-matched reason, and a URL or repo path.

• quickshell_search_implementations

  Search real-world Quickshell shells (Caelestia, Noctalia, and end-4's dots-hyprland) 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 p

• quickshell_style_match

  Analyze an existing Quickshell project and infer reusable UI conventions: colors, corner radius, font sizes, spacing, animation durations, component structure, and naming patterns. Returns evidence-backed findings (values actually present and their frequency), never design opinions. Generation tools can consume this style representation later.

• quickshell_system_diagnostics

  Report verified-only environment problems for Quickshell development: missing commands and services. Only evidence-backed issues are reported. Read-only.

• quickshell_testwrite action

  Run a single machine-readable runtime test against a managed Quickshell session.

• quickshell_test_feature

  Test a feature end-to-end: start an isolated Quickshell session, run the machine-readable test suite, capture a screenshot on failure, and stop the session. Mutating (launches and stops a session).

• quickshell_test_macro

  Define or retrieve a reusable parameterized runtime macro: a named sequence of safe runtime steps that tests can invoke. Pass steps= to save a macro; omit steps to load one by name. Macros are project-scoped for the process. Read-only.

• quickshell_test_record

  Record a list of runtime actions into a reproducible test representation. Uses stable selectors (target + method/property), not fragile generated object ids. Read-only.

• quickshell_test_report

  Produce a structured test report: passed/failed tests, durations, assertions, runtime logs, screenshots, and diagnostics. Suitable for both an LLM and human CI output. Read-only.

• quickshell_test_suitewrite action

  Run multiple named runtime tests in isolation. One failing test never corrupts the rest of the suite. Returns pass/fail totals and per-test results. Mutating.

• quickshell_trace

  Trace a selected runtime interaction across observable state transitions. Reports observed log events; inferred transitions are always kept separate from observed evidence. Read-only.

• quickshell_ui_eval

  HIGH-RISK: evaluate QML/JavaScript in a managed runtime session.

• quickshell_ui_find

  Search the live QML object tree of a managed runtime session by name, type, text, or property. Returns stable references for later runtime tools. Read-only.

• quickshell_ui_get_property

  Read a live QML property value from a managed runtime object via ``qs ipc prop get``. Validates the object/property exist. Read-only.

• quickshell_ui_invoke

  Invoke a QML method on a managed runtime object via ``qs ipc call``. Mutating. Validates the method and arguments; enforces runtime session boundaries; no arbitrary process/system calls.

• quickshell_ui_set_property

  Set a live QML property on a managed runtime object. Mutating.

• quickshell_ui_snapshotwrite action

  Create a single serializable UI snapshot: screenshot, UI tree, live properties, runtime state, timestamp, and project metadata. Comparable for regression detection. Read-only.

• quickshell_ui_tree

  Inspect the live QML object tree of a managed runtime session.

• quickshell_validate_qml

  Statically validate Quickshell/QML source before you run it: unknown types, unknown properties, unknown signals, missing imports, obvious type mismatches, and APIs not available in the requested Quickshell version.

• quickshell_visual_check

  Analyze a runtime screenshot for objective UI problems: clipping, overflow, missing expected elements, unexpected empty areas, misalignment, or off-screen content. Returns observations with confidence and affected regions. It does not claim to prove semantic correctness. Read-only.

• quickshell_visual_diff

  Compare baseline and actual screenshots deterministically for visual-regression testing: diff image, differing pixels metric, configurable threshold, and ignored regions. Read-only.

• quickshell_wayland_layers

  Inspect Wayland layer/surface information for the managed runtime. Requires a compositor adapter; reports a note when unavailable. Read-only.

• quickshell_windows

  Enumerate windows/surfaces belonging to a managed Quickshell runtime session. Read-only. Requires a compositor adapter; when unavailable returns an empty list with an explanatory note (never fails).

• Code scan67 source files scanned25/25
• –Live reliabilityno gateway calls yet and no remote to proben/a
• –Tool poisoningtools not inspected (local package is not executed); not countedn/a
• Auth qualitylocal package, no credentials required12/15
• Maintenancelast push 21 days ago15/15
• Maintainer identityregistry namespace matches repository owner; GitHub account older than a year8/10

Quickshell MCP: common questions

Is Quickshell MCP server safe?

Yes, by our scan: it is graded A (92/100). Read the Quickshell MCP safety report

How do I install Quickshell MCP?

It runs on your machine. Copy the Claude Code, Claude Desktop or Cursor config from the install section.

Does Quickshell MCP need an API key?

Not as far as the registry entry and our scan can tell: no credentials are declared or required.

Is Quickshell MCP maintained?

The last commit was 21 days ago (2026-08-30). The latest release is v2.17.0.