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.

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

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 /<br/>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

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