Archived

This project has been archived by its maintainers, and is no longer receiving any updates.

quickshell-docs-mcp

Live Quickshell documentation for AI coding agents.

PyPI Python codecov

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

pip install quickshell-docs-mcp        # or: uvx quickshell-docs-mcp
From source 
git clone https://github.com/franklinnolasco7/quickshell-docs-mcp
cd quickshell-docs-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
Nix 
nix run github:franklinnolasco7/quickshell-docs-mcp
Docker 
docker build -t quickshell-docs-mcp .
docker run --rm -i quickshell-docs-mcp     # speaks MCP over stdio

Configure

opencode (opencode.json):

{
  "mcp": {
    "quickshell-docs": {
      "type": "local",
      "command": ["/absolute/path/to/quickshell-docs-mcp/.venv/bin/quickshell-docs-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-docs-mcp, 30-day freshness). Relocate or disable with QUICKSHELL_DOCS_MCP_DISK_CACHE, re-tune with QUICKSHELL_DOCS_MCP_DISK_TTL_HOURS.

Tools

Tool What it does
quickshell_search Search type names, guide slugs, optionally full text including deep search over type pages. Call this before writing QML from memory.
quickshell_search_all One-call unified search across Quickshell docs/types, Qt types, official examples, and Caelestia/Noctalia implementations; grouped by source, ranked by relevance
quickshell_find_pattern Describe what you want to build ("Spotlight-style launcher") and get matching real-world implementations with per-pattern API hints and cross-project grouping
quickshell_list_versions Published doc versions and the latest
quickshell_list_types / quickshell_get_type Browse and fetch Quickshell QML type docs
quickshell_list_guide_pages / quickshell_get_guide_page Usage Guide pages as Markdown
quickshell_about / quickshell_changelog About and Changelog pages
quickshell_list_qt_types / quickshell_get_qt_type Qt-side types (QtQuick, Controls, Layouts, ...)
quickshell_list_examples / quickshell_get_example Official example configs
quickshell_search_implementations Find bar/OSD/IPC/... patterns in Caelestia or Noctalia
quickshell_get_implementation Read those files, narrowed via find=
quickshell_explain_error Explain a QML/Quickshell error and suggest a fix, grounded in actual docs
quickshell_stats Session call counts and cache-hit ratio

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.

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:

Source URL What it provides
Quickshell docs https://quickshell.org Type references, usage guide, changelog
Qt docs https://doc.qt.io/qt-6 QtQuick base types (Rectangle, RowLayout, etc.)
Quickshell examples https://git.outfoxxed.me/quickshell/quickshell-examples Official example configs
Caelestia shell https://github.com/caelestia-dots/shell Real-world implementation references
Noctalia shell https://github.com/noctalia-dev/noctalia (legacy-v4) Real-world implementation references

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.

License

MIT

Project links

Data verified by PyPI on Aug 26, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
  • Archived:
Newer release available (1.4.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for franklinnolasco7 from gravatar.com franklinnolasco7

Credits

Author: Frank

GitHub Statistics

Data verified by PyPI on Aug 26, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Provides Extra

dev

Tags

ai documentation llm mcp model-context-protocol qml quickshell wayland

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

quickshell_docs_mcp-1.3.0.tar.gz (169.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

quickshell_docs_mcp-1.3.0-py3-none-any.whl (42.8 kB view details)

Uploaded Python 3

File details

Details for the file quickshell_docs_mcp-1.3.0.tar.gz.

File metadata

  • Download URL: quickshell_docs_mcp-1.3.0.tar.gz
  • Upload date:
  • Size: 169.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for quickshell_docs_mcp-1.3.0.tar.gz
Algorithm Hash digest
SHA256 d5c6045c3c1c917b86da403626d943aeb0d3a0c58af5da73d880899a30c2052d
MD5 c6bc7a5ad419ef076a5857a6cf49a633
BLAKE2b-256 cea03544371493074b7b56e08c23e48fb1cffa8e04a34bce0f719adefbfbe9d3

See more details on using hashes here.

Provenance

The following attestation bundles were made for quickshell_docs_mcp-1.3.0.tar.gz:

Publisher: semantic-release.yml on franklinnolasco7/quickshell-docs-mcp

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file quickshell_docs_mcp-1.3.0-py3-none-any.whl.

File metadata

File hashes

Hashes for quickshell_docs_mcp-1.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 7623cd2965d5925229d7926bf7c527f646922bd1d234a5807d6ece4f98e6c6ee
MD5 da959416c16ad24ff30f2c3f42e3c5c0
BLAKE2b-256 840dbc0c715d2ba0dd8add606dbe6083583f3f902dd581fce930ed7ac52bf7e0

See more details on using hashes here.

Provenance

The following attestation bundles were made for quickshell_docs_mcp-1.3.0-py3-none-any.whl:

Publisher: semantic-release.yml on franklinnolasco7/quickshell-docs-mcp

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

Archived

1.4.0

2 files

This release
Archived

1.3.0 This release

2 files

Archived

1.2.0

2 files

Archived

1.1.0

2 files

Archived

1.0.1

2 files

Archived

1.0.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page