quickshell-mcp

Live Quickshell documentation for AI coding agents.

An MCP server that gives AI agents live access to the official Quickshell documentation, so they stop guessing QML API names from stale training data.

Also included:

• Qt base types (Rectangle, RowLayout, ...) from doc.qt.io
• Official example configs from quickshell-examples
• Real-world implementations, searchable across the Caelestia and Noctalia shells

Every result carries its source URL. When implementations disagree with the docs, the docs win.

Table of Contents

• Install
• Configure
• Tools
• Static validation
• Source Hierarchy
• References
• Development
• Limitations
• License

Install

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

git clone https://github.com/franklinnolasco7/quickshell-mcp
cd quickshell-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

nix run github:franklinnolasco7/quickshell-mcp

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

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).

Set QUICKSHELL_DOCS_MCP_LOG=DEBUG for verbose request logging on stderr. Bulk doc indexes persist on disk (~/.cache/quickshell-mcp, 30-day freshness). Relocate or disable with QUICKSHELL_DOCS_MCP_DISK_CACHE, re-tune with QUICKSHELL_DOCS_MCP_DISK_TTL_HOURS.

Tools

Page-fetching tools accept version="latest" (default) or an explicit version like "v0.3.0". Cache-backed tools accept refresh=True to bypass the 30-minute cache.

Static validation

quickshell_validate_qml statically checks a QML snippet before you run it: unknown Quickshell/Qt types, properties, signals, missing import Quickshell.* statements, obvious scalar type mismatches, and types absent from the requested Quickshell version. It returns structured diagnostics (severity, line/column, confidence, suggested alternatives, and a docs source URL per finding).

It is a lightweight heuristic that complements qmlls, not a replacement: it validates against the same live docs index the other tools use, treats JavaScript bodies as opaque, and reports anything it cannot verify as an info or warning diagnostic rather than a false error. Local component files (a root type matching the filename stem) are skipped rather than flagged.

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

Source Hierarchy

1. Official documentation (quickshell.org, doc.qt.io), authoritative
2. Official examples, next in line
3. Caelestia / Noctalia results, practical references labeled real-world implementation

References

Data comes from these upstream sources:

Development

See CONTRIBUTING.md for setup, workflow, and how to submit changes.

Limitations

• Deep type-page search (include_type_pages=True) fetches every type page once per machine (~15s cold, then cached on disk for 30 days across sessions; refresh=True forces a refetch). Plain name search stays instant.
• Example configs may target a different Quickshell version than yours; listings include a last_modified date so you can judge their age.
• quickshell_validate_qml is heuristic static analysis; it cannot see local components or dynamic JavaScript and does not replace qmlls. Property-level checks fetch the type's docs page (cached), so the first validation of a new type is network-bound.

License

MIT