Quickshell MCP
PYPI · QUICKSHELL-MCP · SCANNED SEP 21
Source-grounded Quickshell, QML, and Qt documentation, examples, and real-world implementations.
Available components
How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. How we score → Why this is hard to score →
Supply Chain Security50
- Malware scan not yet available for this package.Unverified
- No known CVEs affecting this package version or its production dependencies.Pass
- Runs hatchling.build at install time, a recognised native-build step with no shell scripting around it. View diagnostics → Pass
- 0 of 33 dependencies flagged as unhealthy. View diagnostics → Pass
Provenance & Transparency32
- Source repository is publicly reachable at the declared URL. View diagnostics → Pass
- Provenance check failed: no build-provenance attestation is published. See how to fix → View diagnostics → Fail
- License check failed: the license (MIT License) isn't a recognized OSI-approved license. See how to fix → Fail
- Actively maintained (last published 21 days ago).Pass
- Security-disclosure policy not yet verified: we couldn't inspect the source repository.Unverified
Schema Quality & AI Usability71
- AI-judged instruction clarity (good).Pass
- Context-footprint check failed: tool/resource definitions use about 10693 tokens (~104/item across 102 items; 102 tools + 0 resources), over budget; trim descriptions and params. See how to fix → Fail
- Usage-examples check failed: none of the tools include examples. See how to fix → Fail
Stability & Change Management83
- Stability observed for 25 of 30 days with no destabilising changes; credit accrues until the full window elapses.Partial
Tool Coverage71
- 100% of tools have a non-trivial description (not blank, and not just the tool's name).Pass
- 0% of tool parameters carry a description.Fail
- Structured output schemas are declared (7% of tools); any adoption earns full credit.Pass
Tool Safety75
- No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.Pass
- 0 of 2 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation; "quickshell_ui_eval" implies "eval" and declares no destructiveHint at all, which the MCP spec reads as destructive by default. See how to fix → Fail
- An AI judge read all 102 captured unit(s) of tool text and found none that tries to manipulate the model reading it.Pass
Capabilities100
- Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.Pass
How do I install the Quickshell MCP server?
Quickshell MCP runs locally as a PyPI package, launched with uvx quickshell-mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.
pypi · quickshell-mcp
claude mcp add franklinnolasco7-quickshell-mcp -- uvx quickshell-mcp
{
"mcpServers": {
"franklinnolasco7-quickshell-mcp": {
"command": "uvx",
"args": [
"quickshell-mcp"
]
}
}
} {
"servers": {
"franklinnolasco7-quickshell-mcp": {
"command": "uvx",
"args": [
"quickshell-mcp"
]
}
}
} codex mcp add franklinnolasco7-quickshell-mcp -- uvx quickshell-mcp
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"franklinnolasco7-quickshell-mcp": {
"type": "local",
"command": [
"uvx",
"quickshell-mcp"
],
"enabled": true
}
}
} openclaw mcp add franklinnolasco7-quickshell-mcp --command uvx --arg quickshell-mcp
mcp_servers:
franklinnolasco7-quickshell-mcp:
command: "uvx"
args: ["quickshell-mcp"] {
"McpServers": {
"franklinnolasco7-quickshell-mcp": {
"Transport": "stdio",
"Command": "uvx",
"Arguments": [
"quickshell-mcp"
]
}
}
} assistant mcp add franklinnolasco7-quickshell-mcp -t stdio -c uvx -a quickshell-mcp
{
"mcpServers": {
"franklinnolasco7-quickshell-mcp": {
"command": "uvx",
"args": [
"quickshell-mcp"
]
}
}
} Every change we have recorded for this component, newest first. Security-relevant changes are always shown. ▲ marks a change for the better, ▼ a change for the worse; unmarked changes are neutral.
- 21 Sept 26 0
- Security disclosure: fail → unverified ▼ functional
- 20 Sept 26 +1
No change was recorded against any check on this day. Stability & Change Management went from 77 to 80. That category is still filling its 30-day observation window: 23 days of observed history at the previous scan, 24 at this one. The score rises as the window fills, whether or not the server changes.
- 18 Sept 26 +1
No change was recorded against any check on this day. Stability & Change Management went from 70 to 73. That category is still filling its 30-day observation window: 21 days of observed history at the previous scan, 22 at this one. The score rises as the window fills, whether or not the server changes.
- 16 Sept 26 +1
No change was recorded against any check on this day. Stability & Change Management went from 63 to 67. That category is still filling its 30-day observation window: 19 days of observed history at the previous scan, 20 at this one. The score rises as the window fills, whether or not the server changes.
- 14 Sept 26 +1
No change was recorded against any check on this day. Stability & Change Management went from 57 to 60. That category is still filling its 30-day observation window: 17 days of observed history at the previous scan, 18 at this one. The score rises as the window fills, whether or not the server changes.
- 12 Sept 26 +1
No change was recorded against any check on this day. Stability & Change Management went from 50 to 53. That category is still filling its 30-day observation window: 15 days of observed history at the previous scan, 16 at this one. The score rises as the window fills, whether or not the server changes.
- 10 Sept 26 +1
No change was recorded against any check on this day. Stability & Change Management went from 43 to 47. That category is still filling its 30-day observation window: 13 days of observed history at the previous scan, 14 at this one. The score rises as the window fills, whether or not the server changes.
- 7 Sept 26 −14
- Malware scan: pass → unverified ▼ security
Diagnostic detail from the automated scan of this channel: what the scanner observed at each step, so you can see exactly where a check passed or failed. It is informational only and never changes the trust score.
Captured 21 Sept 2026 · Analysed pypi/quickshell-mcp@2.17.0
Provenance No attestation
The registry publishes no build provenance for this version, so there is nothing to verify.
| Result | No attestation |
|---|---|
| Ecosystem | pypi |
Background: How many MCP packages publish verified provenance →
Install scripts 1 script
| Hook | Tier | Command |
|---|---|---|
| build_backend | allowlisted | hatchling.build |
Background: Why install scripts are a supply-chain risk →
Dependencies 33 packages
| Packages resolved | 33 |
|---|---|
| Tree resolution | Complete |
Background: SBOMs and build attestations, explained →
The tools this component advertises to a client, with an estimated token cost for each. Expand a tool to see its parameters and schema. The per-tool counts are indicative and are not scored directly; the schema's total context footprint is one signal in Schema Quality & AI Usability. A tool's description is untrusted text the model reads on every call, which is what makes this list a security surface and not just an inventory: how tool poisoning works →
quickshell_project_compatibility ~92
Analyze a whole project's Quickshell API compatibility against a target version: unavailable, deprecated, or changed APIs with affected files and concrete locations. Reuses the version compatibility engine. A verdict of 'uncertain' means the docs did not prove availability either way — it is never reported as a runtime incompatibility.
| Name | Type | Req | Description |
|---|---|---|---|
| project | string | yes | – |
| version | string | – | – |
No output schema declared.
No examples provided.
quickshell_project_config ~59
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.
| Name | Type | Req | Description |
|---|---|---|---|
| project | string | yes | – |
No output schema declared.
No examples provided.
quickshell_project_dependencies ~97
Detect a Quickshell project's dependencies from source and configuration, without executing anything. Classes are: - required: Quickshell and Qt modules the project imports - optional: imports that match known namespaces without local files - detected: runtime hooks, services, config keywords, environment variable references - missing: imports that resolve to neither a known namespace nor a local component
| Name | Type | Req | Description |
|---|---|---|---|
| project | string | yes | – |
No output schema declared.
No examples provided.
quickshell_project_find ~92
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). Returns file, location, match context, and why the result matched. Exact textual matches are ranked first; semantic matches follow.
| Name | Type | Req | Description |
|---|---|---|---|
| project | string | yes | – |
| query | string | yes | – |
No output schema declared.
No examples provided.
quickshell_project_lint ~91
Run quality-oriented lint checks across a Quickshell project. Every rule has a stable diagnostic code, severity, explanation, and remediation. Rules are conservative and evidence-based; they flag suspicious patterns (duplicate imports, duplicate object ids, suspicious timers) rather than subjective style opinions. The rule table is extensible for future additions.
| Name | Type | Req | Description |
|---|---|---|---|
| project | string | yes | – |
No output schema declared.
No examples provided.
quickshell_project_map ~104
Build a machine-readable project graph showing relationships between QML components, imports, service dependencies, entrypoints, and module dependencies. Relies on reliable static relationships. The output clearly distinguishes: - confirmed relationships (directly observed import statements, type matches against local file stems) - inferred relationships (references that could not be proven local) Reports cyclic component usage and references that match no local file and no known namespace.
| Name | Type | Req | Description |
|---|---|---|---|
| project | string | yes | – |
No output schema declared.
No examples provided.
quickshell_project_memory ~121
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.
| Name | Type | Req | Description |
|---|---|---|---|
| action | string | – | – |
| content | – | – | – |
| evidence | – | – | – |
| key | – | – | – |
| project | string | yes | – |
| scope | string | – | – |
No output schema declared.
No examples provided.
quickshell_project_migrate ~109
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. Never modifies files. Every proposed edit carries file, line, and old/new API context so it can be applied safely. Reuses the existing migration engine per file.
| Name | Type | Req | Description |
|---|---|---|---|
| from_version | string | yes | – |
| project | string | yes | – |
| to_version | string | yes | – |
No output schema declared.
No examples provided.
quickshell_project_validate ~104
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. Results are grouped by file and severity. One bad file never prevents analysis of the rest: unreadable files are reported and skipped. Reuses the existing validator rather than duplicating logic.
| Name | Type | Req | Description |
|---|---|---|---|
| project | string | yes | – |
| version | string | – | – |
No output schema declared.
No examples provided.
quickshell_provenance ~68
Return provenance for knowledge results: source, version, URL, and authority level (docs > examples > real-world), so higher-level results can cite them. Read-only.
| Name | Type | Req | Description |
|---|---|---|---|
| limit | integer | – | – |
| query | string | yes | – |
| version | string | – | – |
No output schema declared.
No examples provided.
quickshell_refactor ~93
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.
| Name | Type | Req | Description |
|---|---|---|---|
| new | string | yes | – |
| old | string | yes | – |
| project | string | yes | – |
No output schema declared.
No examples provided.
quickshell_regression_detect ~90
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.
| Name | Type | Req | Description |
|---|---|---|---|
| actual_screenshot | – | – | – |
| baseline_screenshot | – | – | – |
| project | string | yes | – |
| threshold | integer | – | – |
| version | string | – | – |
No output schema declared.
No examples provided.
quickshell_reload ~61
Reload a managed runtime session, preserving session tracking. Reuses the lifecycle implementation; cleans up after failed reloads. Never touches production Quickshell processes. Mutating.
| Name | Type | Req | Description |
|---|---|---|---|
| hard | boolean | – | – |
| session_id | string | yes | – |
No output schema declared.
No examples provided.
quickshell_root_cause ~85
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.
| Name | Type | Req | Description |
|---|---|---|---|
| code | – | – | – |
| error | – | – | – |
| filename | – | – | – |
| project | – | – | – |
| session_id | – | – | – |
| version | string | – | – |
No output schema declared.
No examples provided.
quickshell_runtime_dependencies ~75
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.
| Name | Type | Req | Description |
|---|---|---|---|
| project | string | yes | – |
No output schema declared.
No examples provided.
quickshell_runtime_diagnose ~60
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.
| Name | Type | Req | Description |
|---|---|---|---|
| session_id | string | yes | – |
No output schema declared.
No examples provided.
quickshell_runtime_errors ~79
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.
| Name | Type | Req | Description |
|---|---|---|---|
| limit | integer | – | – |
| session_id | string | yes | – |
No output schema declared.
No examples provided.
quickshell_runtime_logs ~68
Return structured logs from a runtime session with optional filtering by stream (stdout/stderr), text, and a bounded limit. Read-only.
| Name | Type | Req | Description |
|---|---|---|---|
| limit | integer | – | – |
| session_id | string | yes | – |
| severity | – | – | – |
| stream | – | – | – |
| text | – | – | – |
No output schema declared.
No examples provided.
quickshell_runtime_ping ~49
Lightweight readiness/health check for a runtime session. Distinguishes: process_running, exited (with exit code), or unhealthy. Fast, read-only.
| Name | Type | Req | Description |
|---|---|---|---|
| session_id | string | yes | – |
No output schema declared.
No examples provided.
quickshell_runtime_reset ~59
Reset a managed runtime session to a clean state. Stops the current session, cleans up its isolated temp dirs, and starts a fresh session with the same profile under a new session id. Mutating.
| Name | Type | Req | Description |
|---|---|---|---|
| session_id | string | yes | – |
No output schema declared.
No examples provided.
quickshell_runtime_start ~117
Start a managed, isolated Quickshell runtime session for a project. Launches ``qs`` with isolated XDG directories so it never touches your real desktop session or other quickshell instances. Returns a session id and tracks the process for later status, logs, ping, stop, and reset. This is a mutating operation: it launches a process.
| Name | Type | Req | Description |
|---|---|---|---|
| arguments | – | – | – |
| compositor | – | – | – |
| config_dir | – | – | – |
| entrypoint | – | – | – |
| environment | – | – | – |
| project | string | yes | – |
No output schema declared.
No examples provided.
quickshell_runtime_status ~48
Return structured status for a runtime session: session id, running state, PID, startup duration, exit code, and profile identity. Read-only.
| Name | Type | Req | Description |
|---|---|---|---|
| session_id | string | yes | – |
No output schema declared.
No examples provided.
quickshell_runtime_stop ~62
Stop a managed runtime session safely (SIGTERM, then SIGKILL on timeout). Handles already-exited and orphaned processes; stops only the tracked session's process group, never unrelated user processes. Mutating.
| Name | Type | Req | Description |
|---|---|---|---|
| session_id | string | yes | – |
No output schema declared.
No examples provided.
quickshell_screenshot ~143
Capture a bounded screenshot of a managed Quickshell runtime session. Requires the ``grim`` compositor screenshot tool on PATH. **Full-desktop capture is disabled by default.** Pass ``rectangle=`` with ``x``, ``y``, ``width``, ``height`` to target a specific region. Object-derived geometry is not yet available and will report an explanatory note. Set ``QUICKSHELL_DOCS_MCP_ALLOW_FULLSCREEN_CAPTURE=1`` at server launch to allow full-screen captures (high-risk: includes all desktop content). Read-only.
| Name | Type | Req | Description |
|---|---|---|---|
| object_name | – | – | – |
| rectangle | – | – | – |
| session_id | string | yes | – |
No output schema declared.
No examples provided.
quickshell_screenshot_diff ~64
Compare two runtime screenshots with ImageMagick ``compare``. Returns whether they differ, the diff image path, and a metric. Deterministic for CI. Read-only.
| Name | Type | Req | Description |
|---|---|---|---|
| actual | string | yes | – |
| baseline | string | yes | – |
| output | – | – | – |
No output schema declared.
No examples provided.
quickshell_screenshot_region ~100
Capture a region-based screenshot of a managed runtime, preferring an object-derived region over manual coordinates. Read-only; requires grim. Pass ``rectangle=`` (x, y, width, height) to capture a bounded region. Full-desktop capture is disabled by default; object-derived geometry requires a compositor adapter (reports an explanatory note).
| Name | Type | Req | Description |
|---|---|---|---|
| object_name | – | – | – |
| rectangle | – | – | – |
| session_id | string | yes | – |
No output schema declared.
No examples provided.
quickshell_search ~483
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.
| Name | Type | Req | Description |
|---|---|---|---|
| include_content | boolean | – | – |
| include_type_pages | boolean | – | – |
| query | string | yes | – |
| refresh | boolean | – | – |
| version | string | – | – |
No output schema declared.
No examples provided.
quickshell_search_all ~315
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. Use this when you don't know which specialized tool fits ("how do I make a workspace bar?", "create a volume OSD") or as a first pass before drilling in. API-shaped queries ("PanelWindow", "exclusive zones") rank exact type matches first; feature requests rank working implementations first. This is breadth over depth: follow up with quickshell_get_type / quickshell_get_guide_page / quickshell_get_qt_type / quickshell_get_example / quickshell_get_implementation for full content. include_content=True also full-text-searches guide-page bodies (slower on first call, then cached). limit_per_source caps entries per source (default 4, max 10). version pins a Quickshell release ('latest' resolves at runtime); refresh=True bypasses the cache.
| Name | Type | Req | Description |
|---|---|---|---|
| include_content | boolean | – | – |
| limit_per_source | integer | – | – |
| query | string | yes | – |
| refresh | boolean | – | – |
| version | string | – | – |
No output schema declared.
No examples provided.
quickshell_search_implementations ~257
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 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', source='noctalia', or source='dots-hyprland'; 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.
| Name | Type | Req | Description |
|---|---|---|---|
| limit | integer | – | – |
| query | string | yes | – |
| source | string | – | – |
No output schema declared.
No examples provided.
quickshell_stats ~62
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.
Input schema present but exposes no named parameters.
No output schema declared.
No examples provided.
quickshell_style_match ~82
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.
| Name | Type | Req | Description |
|---|---|---|---|
| project | string | yes | – |
No output schema declared.
No examples provided.
quickshell_system_diagnostics ~37
Report verified-only environment problems for Quickshell development: missing commands and services. Only evidence-backed issues are reported. Read-only.
Input schema present but exposes no named parameters.
No output schema declared.
No examples provided.
quickshell_task_plan ~75
Plan a development request with the minimal tool set: inspect the project first, select the fewest tools that accomplish the intent, and stop when verification would confirm the change. Advisory and read-only; planning never executes anything.
| Name | Type | Req | Description |
|---|---|---|---|
| project | – | – | – |
| request | string | yes | – |
| version | string | – | – |
No output schema declared.
No examples provided.
quickshell_test ~121
Run a single machine-readable runtime test against a managed Quickshell session. A test has a name, a list of steps (wait, invoke, set_property), and a list of assertions (object_exists, property_equals, property_contains, property_matches, visible, enabled, text_matches, window_exists). Returns pass/fail, per-step and per-assertion results, duration, and an optional screenshot on failure. Mutating (drives the runtime).
| Name | Type | Req | Description |
|---|---|---|---|
| session_id | string | yes | – |
| test | object | yes | – |
No output schema declared.
No examples provided.
quickshell_test_feature ~100
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).
| Name | Type | Req | Description |
|---|---|---|---|
| compositor | – | – | – |
| config_dir | – | – | – |
| entrypoint | – | – | – |
| environment | – | – | – |
| project | string | yes | – |
| screenshot_on_fail | boolean | – | – |
| tests | array | yes | – |
No output schema declared.
No examples provided.
quickshell_test_macro ~76
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.
| Name | Type | Req | Description |
|---|---|---|---|
| name | string | yes | – |
| steps | – | – | – |
No output schema declared.
No examples provided.
quickshell_test_record ~59
Record a list of runtime actions into a reproducible test representation. Uses stable selectors (target + method/property), not fragile generated object ids. Read-only.
| Name | Type | Req | Description |
|---|---|---|---|
| actions | array | yes | – |
| session_id | string | yes | – |
No output schema declared.
No examples provided.
quickshell_test_report ~64
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.
| Name | Type | Req | Description |
|---|---|---|---|
| session_id | string | yes | – |
| suite | object | yes | – |
No output schema declared.
No examples provided.
quickshell_test_suite ~61
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.
| Name | Type | Req | Description |
|---|---|---|---|
| session_id | string | yes | – |
| tests | array | yes | – |
No output schema declared.
No examples provided.
quickshell_trace ~63
Trace a selected runtime interaction across observable state transitions. Reports observed log events; inferred transitions are always kept separate from observed evidence. Read-only.
| Name | Type | Req | Description |
|---|---|---|---|
| action | string | yes | – |
| session_id | string | yes | – |
| steps | integer | – | – |
No output schema declared.
No examples provided.
quickshell_ui_eval ~96
HIGH-RISK: evaluate QML/JavaScript in a managed runtime session. Explicitly opt-in, session-scoped, with an execution timeout and output limits. No filesystem or process access is granted. Prefer quickshell_ui_get_property / quickshell_ui_invoke for controlled reads and calls.
| Name | Type | Req | Description |
|---|---|---|---|
| js_code | string | yes | – |
| session_id | string | yes | – |
| timeout | integer | – | – |
No output schema declared.
No examples provided.
quickshell_ui_find ~59
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.
| Name | Type | Req | Description |
|---|---|---|---|
| query | string | yes | – |
| session_id | string | yes | – |
No output schema declared.
No examples provided.
quickshell_ui_get_property ~65
Read a live QML property value from a managed runtime object via ``qs ipc prop get``. Validates the object/property exist. Read-only.
| Name | Type | Req | Description |
|---|---|---|---|
| property_name | string | yes | – |
| session_id | string | yes | – |
| target | string | yes | – |
No output schema declared.
No examples provided.
quickshell_ui_invoke ~79
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.
| Name | Type | Req | Description |
|---|---|---|---|
| arguments | – | – | – |
| method | string | yes | – |
| session_id | string | yes | – |
| target | string | yes | – |
No output schema declared.
No examples provided.
quickshell_ui_set_property ~80
Set a live QML property on a managed runtime object. Mutating. Requires an explicit runtime session, validates the property exists, returns the old and new values, and never modifies project files.
| Name | Type | Req | Description |
|---|---|---|---|
| property_name | string | yes | – |
| session_id | string | yes | – |
| target | string | yes | – |
| value | string | yes | – |
No output schema declared.
No examples provided.
quickshell_ui_snapshot ~101
Create a single serializable UI snapshot: screenshot, UI tree, live properties, runtime state, timestamp, and project metadata. Comparable for regression detection. Read-only. Pass ``rectangle=`` to capture a bounded screenshot region; full-desktop capture is disabled by default (see quickshell_screenshot).
| Name | Type | Req | Description |
|---|---|---|---|
| include_tree | boolean | – | – |
| object_name | – | – | – |
| rectangle | – | – | – |
| session_id | string | yes | – |
No output schema declared.
No examples provided.
quickshell_ui_tree ~61
Inspect the live QML object tree of a managed runtime session. Returns a compact, depth-limited hierarchy from the injected 'inspector' IpcHandler target. Read-only.
| Name | Type | Req | Description |
|---|---|---|---|
| depth | integer | – | – |
| session_id | string | yes | – |
No output schema declared.
No examples provided.
quickshell_validate_qml ~282
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. Pass the QML source; optionally pin a Quickshell version (defaults to the latest) and give a filename so a root type matching the file stem is treated as a local component instead of an unknown type. The check is a lightweight heuristic that complements qmlls, not a replacement: it validates types/properties/signals against the Quickshell and Qt docs, skips JavaScript bodies, and reports things it cannot resolve as info diagnostics rather than errors. Returns structured diagnostics with line/column, severity, confidence, and a docs source URL for each finding. Use this while writing a config (e.g. after noticing 'Cannot assign to non-existent property' in your logs) to catch typos early: - unknown type or namespace - property/signal/method not documented on a type - invalid assignment to a scalar-typed property - missing 'import Quickshell.X' for a used namespace - type not present in the requested Quickshell version
| Name | Type | Req | Description |
|---|---|---|---|
| filename | – | – | – |
| source | string | yes | – |
| version | string | – | – |
No output schema declared.
No examples provided.
quickshell_visual_check ~122
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. Pass an explicit screenshot_path to analyze an existing file, or rectangle= to capture a bounded region. Full-desktop capture is disabled by default (see quickshell_screenshot).
| Name | Type | Req | Description |
|---|---|---|---|
| object_name | – | – | – |
| rectangle | – | – | – |
| screenshot_path | – | – | – |
| session_id | string | yes | – |
No output schema declared.
No examples provided.
quickshell_visual_diff ~74
Compare baseline and actual screenshots deterministically for visual-regression testing: diff image, differing pixels metric, configurable threshold, and ignored regions. Read-only.
| Name | Type | Req | Description |
|---|---|---|---|
| actual | string | yes | – |
| baseline | string | yes | – |
| ignored_regions | – | – | – |
| output | – | – | – |
| threshold | integer | – | – |
No output schema declared.
No examples provided.
What is the Quickshell MCP server?
Quickshell MCP is listed in the public MCP registry as io.github.franklinnolasco7/quickshell-mcp. Source-grounded Quickshell, QML, and Qt documentation, examples, and real-world implementations. This page covers its PyPI package (quickshell-mcp).
Is the Quickshell MCP server safe to use?
Quickshell MCP scores 60 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 21 September 2026. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.
What tools does the Quickshell MCP server expose?
Quickshell MCP exposes 102 tools: quickshell_list_versions, quickshell_about, quickshell_changelog, quickshell_list_guide_pages, quickshell_get_guide_page, and 97 more. Their descriptions and schemas cost roughly 10,693 tokens of context every time the server is loaded.
Is the Quickshell MCP server still maintained?
Quickshell MCP is still listed as active in the MCP registry. We last reached this channel on 21 September 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.