cudaq-docs-mcp
An MCP server that serves NVIDIA CUDA-Q documentation, API reference, and runnable examples to AI agents: version-pinned to the cudaq you actually have installed.
Community project, not affiliated with or endorsed by NVIDIA. CUDA-Q is a trademark of NVIDIA Corporation.
Why
Quantum SDKs move faster than model training data. Ask an AI assistant to write CUDA-Q code and it answers from whatever it memorized: renamed APIs, retired target names, install steps for a version you do not run. The failure is version skew, and it lands where onboarding matters most: the first ten minutes.
This server gives any MCP-capable agent the current answer instead. Documentation search, exact API symbol resolution, complete runnable examples, and a backend-selection guide, all served from an index of the docs that match your installed cudaq package. No API keys and no embeddings: SQLite full-text search with BM25 ranking, on your machine, offline once the index exists.
Quick start
Register the server with your client; on first use it downloads a prebuilt index (a couple of megabytes) automatically. Building locally is only needed for versions without a prebuilt asset:
uvx cudaq-docs-mcp build --version 0.14.0
Claude Code
claude mcp add cudaq-docs -- uvx cudaq-docs-mcp
Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json), or any client that takes a JSON server map:
{
"mcpServers": {
"cudaq-docs": {
"command": "uvx",
"args": ["cudaq-docs-mcp"]
}
}
}
VS Code (.vscode/mcp.json):
{
"servers": {
"cudaq-docs": {
"type": "stdio",
"command": "uvx",
"args": ["cudaq-docs-mcp"]
}
}
}
Prefer pip? pip install cudaq-docs-mcp and use cudaq-docs-mcp as the command.
| Tool | What it returns |
|---|
search_docs(query, version?, limit?) | Ranked doc excerpts with breadcrumbs and canonical URLs |
get_page(path, version?) | One full documentation page as clean markdown |
find_api(name, language?, version?) | Exact Python or C++ symbol, kind, doc URL, and an excerpt |
search_examples(query, language?, version?, limit?) | Complete runnable programs from the CUDA-Q repository at the matching release |
list_targets(category?) | All 24 execution targets: simulators, hardware providers, and clouds, with selection snippets and when-to-use guidance |
Resources: cudaq://versions (installed and indexed versions) and cudaq://llms.txt (CUDA-Q's own llms.txt for the served version).
Version-pinned answers
Every tool resolves its docs version in this order:
- An explicit
version argument ("0.15.0", "latest")
- The installed cudaq package, detected from distribution metadata (cudaq is never imported)
latest
Indexes are per-version. When a pinned index is missing the server says so in the response and serves latest instead, with the one command that fixes it. Skew becomes visible instead of silent.
How it works
CUDA-Q publishes the raw material: a Sphinx inventory (objects.inv) listing every page and API symbol, markdown mirrors of each docs page, a per-version llms.txt, and example sources in the repository. This server builds on that groundwork:
objects.inv is the crawl manifest and the API symbol table: no scraping heuristics- each markdown mirror is cleaned of theme chrome, code blocks are rebuilt with their language, and heading anchors are preserved for deep links
- pages are chunked by heading and indexed in SQLite FTS5 (porter stemming, BM25 ranking)
- examples, snippets, and application sources are fetched from the GitHub release tag that matches the docs version
The whole index is one SQLite file per version in your cache directory (cudaq-docs-mcp info shows where). A nightly workflow rebuilds the latest index so refreshes stay a download, not a build.
CLI
cudaq-docs-mcp
cudaq-docs-mcp build
cudaq-docs-mcp build --version 0.15.0
cudaq-docs-mcp info
Set CUDAQ_DOCS_MCP_AUTOBUILD=1 to build automatically on first use, and CUDAQ_DOCS_MCP_CACHE to relocate the cache.
Roadmap
- Prebuilt indexes for pinned release versions, not just
latest
- An eval set of real developer questions, with published retrieval scores
- CUDA-QX library docs
Contributing
Issues and PRs are welcome. Commits need a DCO sign-off (git commit -s); see CONTRIBUTING.md. Built in the open with Claude Code.
License
Apache-2.0. Documentation content belongs to NVIDIA Corporation & Affiliates, originates from the Apache-2.0 licensed NVIDIA/cuda-quantum repository, and every served result links back to the canonical page. See NOTICE.