Quickshell MCP

quickshell-mcp

An MCP server that connects AI coding agents to live Quickshell, QML, and Qt documentation.

---

Search APIs, discover implementation patterns, explain errors, validate QML, inspect a project, run tests, and profile a live shell before your agent writes or runs code.

Why

Quickshell changes quickly, and AI coding agents can generate QML from outdated or incomplete training data. quickshell-mcp lets agents verify APIs against current documentation, find existing implementation patterns, validate generated QML, and inspect or test a project instead of guessing from memory.

[!IMPORTANT]

When sources disagree, official documentation always takes precedence.

Table of Contents

• Quick start
• What it provides
• External tools
• Knowledge sources
• Configure
• Tools
• Typical workflow
• Advanced usage
• Source priority
• Caching
• References
• Limitations
• License

Quick start

pip install quickshell-mcp        # or: uvx quickshell-mcp

Then point your MCP client at it (see Configure below).

Also installable via the Model Context Protocol Registry.

Install from source

git clone https://github.com/franklinnolasco7/quickshell-mcp

cd quickshell-mcp python3 -m venv .venv && source .venv/bin/activate pip install -e .

</details>

Install with Nix

nix run github:franklinnolasco7/quickshell-mcp

Install with Docker

docker build -t quickshell-mcp .

docker run --rm -i quickshell-mcp # speaks MCP over stdio

</details>

What it provides

External tools

Most tools need nothing beyond the quickshell-mcp package. The ones that inspect a real desktop detect their dependency at runtime and report it as unavailable when missing, instead of failing. This applies to runtime sessions, UI inspection, and the desktop adapters.

The headless CI shell (nix develop .#ci) packages quickshell, weston, grim, and imagemagick for running runtime-test and screenshot jobs without a desktop.

Knowledge sources

Six sources back the server: Quickshell docs, Qt/QML docs, official Quickshell examples, and three real-world shells (Caelestia, Noctalia, dots-hyprland). The shells are practical reference material, not authoritative API definitions. See Source priority for how conflicts resolve.

Configure

opencode (opencode.json):

{

"mcp": { "quickshell": { "type": "local", "command": ["/absolute/path/to/quickshell-mcp/.venv/bin/quickshell-mcp"], "enabled": true } } }

Claude Desktop: same JSON under claude_desktop_config.json, wrapped in mcpServers.

For HTTP transport, set QUICKSHELL_DOCS_MCP_TRANSPORT=http (plus optional HOST/PORT).

[!TIP]

Set QUICKSHELL_DOCS_MCP_LOG=DEBUG for verbose request logging on stderr.

The QUICKSHELL_DOCS_MCP_* environment variable prefix is retained for backwards compatibility with earlier releases.

Tools

For the full per-tool list, grouped by capability with mutating and high-risk tools flagged, see docs/TOOLS.md.

Typical workflow

flowchart TD

A[Search] --> B[Find implementation pattern] B --> C[Verify API] C --> D[Write QML] D --> E[Validate] E -->|errors| F[Fix errors] F --> E E -->|clean| G[Done]

classDef discover fill:#cdeaff,stroke:#1c6dd0,stroke-width:1px,color:#0b3661 classDef build fill:#ffe3c2,stroke:#d8871b,stroke-width:1px,color:#5c3a05 classDef check fill:#c9f2d8,stroke:#1f9e5c,stroke-width:1px,color:#0b3d24 classDef fix fill:#ffd1d1,stroke:#d13b3b,stroke-width:1px,color:#5c0b0b classDef done fill:#e3d6ff,stroke:#7b3ff0,stroke-width:2px,color:#2f1466

class A,B,C discover class D build class E check class F fix class G done

Example

Instead of asking an AI agent to guess how to create a workspace indicator in Quickshell, the agent can search for the API, find existing implementations, verify the requested version, generate the QML, and validate it before running it:

flowchart LR

A[quickshell_search_all] --> B[quickshell_find_pattern] B --> C[quickshell_list_versions / quickshell_get_type] C --> D[quickshell_generate_component] D --> E[quickshell_validate_qml] E --> F[quickshell_explain_error]

classDef tool fill:#cdeaff,stroke:#1c6dd0,stroke-width:1px,color:#0b3661 classDef action fill:#ffe3c2,stroke:#d8871b,stroke-width:1px,color:#5c3a05 classDef debug fill:#ffd1d1,stroke:#d13b3b,stroke-width:1px,color:#5c0b0b

class A,B,C tool class D,E action class F debug

Advanced usage

Static validation, version compatibility, migration, component generation, and the coding assistant : catch bad QML, verify API support per release, plan upgrades, generate components, or route a whole development task through the assistant

Static validation

quickshell_validate_qml checks QML against the same Quickshell and Qt documentation indexes the other tools use. It catches:

• Unknown Quickshell and Qt types
• Unknown properties, methods, and signals
• Missing imports
• Obvious type mismatches
• APIs unavailable in the requested Quickshell version

quickshell_validate_qml complements qmlls; it does not replace it. Dynamic JavaScript and local component resolution are outside its scope.

{"source": "PanelWindow { foo: 123 }", "version": "latest", "filename": "panel.qml"}

Version compatibility

quickshell_check_compatibility checks whether a Quickshell API, QML property/method/signal, type, or whole snippet works on a specific release. Pass one of api, type, or code; choose the release with version (or use from_version/to_version for a range).

It does not judge from the latest docs page alone. It cross-references the requested version's type index and pages plus the changelog, and returns uncertain when the evidence is not enough. Qt/QML types (Rectangle, Item, ...) show as compatible with origin: "qt", because your Qt version sets their availability, not the Quickshell one.

{"api": "PanelWindow.exclusiveZone", "version": "v0.2.0"}

{"api": "Quickshell.shellRoot", "version": "v0.3.1"} {"code": "PanelWindow { exclusiveZone: 1 }", "version": "v0.1.0"}

The result includes the verdict, the version evidence (earliest/latest known), any rename or change with a likely replacement, the matching changelog entry, and cited documentation URLs.

Migrating between versions

quickshell_migrate analyzes what a QML config must change to keep working when upgrading from one Quickshell version to another. Pass the QML source (or a single api/type), plus from_version and to_version (both required, ordered oldest to newest).

It reports every removed, renamed, deprecated, or changed API with severity, location, the old and new API, why it must change, a suggested migration, confidence, and a cited source. It also scans the breaking-change changelog entries between the versions that mention the referenced symbols, so a rename that landed at an intermediate release is reported with the version it landed in. Findings are classified definite (backed by the docs or changelog), likely (documented but low-impact, e.g. deprecation), or manual_review (evidence suggests a change but the exact migration is not provable).

The tool analyzes and recommends; it never rewrites code or files.

{

"code": "Quickshell { shellRoot: \"/tmp\" }\nPanelWindow { exclusiveZone: 1 }", "from_version": "v0.1.0", "to_version": "v0.3.1" }

The report includes the overall verdict (compatible, changes_required, uncertain), the per-issue findings, and an ordered migration plan.

Component generation

quickshell_generate_component turns a plain-language description into a minimal QML component, e.g. "Create a Hyprland workspace indicator", "animated volume OSD", "top bar with workspaces, clock and system tray", "popup control center", or "notification popup".

{"description": "volume OSD", "version": "latest", "compositor": "hyprland"}

The generator searches for the request (using the same search and pattern tools as the rest), builds a small