quickshell-mcp

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

Search APIs, discover implementation patterns, explain errors, and validate QML 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, and validate generated QML instead of guessing from memory.

[!IMPORTANT] When sources disagree, official documentation always takes precedence.

Table of Contents

• Quick start
• What it provides
• 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

Knowledge sources

flowchart LR
    A[Quickshell docs]
    B[Qt/QML docs]
    C[Official examples]
    D[Caelestia]
    E[Noctalia]
    M((quickshell-mcp))
    Agent[AI coding agent]

    A --> M
    B --> M
    C --> M
    D --> M
    E --> M
    M --> Agent

    classDef official fill:#cdeaff,stroke:#1c6dd0,stroke-width:1px,color:#0b3661
    classDef community fill:#ffe3c2,stroke:#d8871b,stroke-width:1px,color:#5c3a05
    classDef core fill:#c9f2d8,stroke:#1f9e5c,stroke-width:2px,color:#0b3d24
    classDef agent fill:#ead6ff,stroke:#8a3ff0,stroke-width:1px,color:#3a1466

    class A,B,C official
    class D,E community
    class M core
    class Agent agent

Official documentation is authoritative. Examples and real-world implementations provide practical reference material (see Source priority).

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

Discovery

Documentation

Qt / QML

Examples & implementations

Debugging & session

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.

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[generate QML]
    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 action
    class E,F debug

Advanced usage

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

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

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

Source priority

When sources disagree, in order of authority:

1. Official Quickshell documentation
2. Official Qt documentation
3. Official Quickshell examples
4. Real-world implementations

Real-world implementations are practical references, not authoritative API definitions.

Caching

Documentation indexes are cached locally under ~/.cache/quickshell-mcp.

Use refresh=True to bypass the short-lived cache where supported. The cache location and disk TTL can be configured with the existing QUICKSHELL_DOCS_MCP_* environment variables.

References

Development

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

Limitations

• Validation is static and heuristic; it complements qmlls.
• Dynamic JavaScript and local component resolution are limited.
• Official examples may target different Quickshell versions.
• Deep documentation searches can be slower on a cold cache.
• Real-world implementations are references and may contain outdated patterns.

License

MIT