io.github.Blite-HQ/qnexus-mcp
MCP server for Quantinuum Nexus, wrapping the qnexus SDK. Not affiliated with Quantinuum.
Open source Open in the app JSON README (API)
About
MCP server for Quantinuum Nexus, wrapping the qnexus SDK. Not affiliated with Quantinuum.
Details
- Kind
- MCP servers
- Topic
- Developer tools
- Publisher
- blite-hq
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.0
- Stars
- 1
- Open pull requests
- 9
- Last push
- 2026-09-08T04:34:14Z
- Repository state
- ativo
- Language
- Python
- License
- Apache-2.0
- Added
- 2026-08-29 03:01:43
- Updated
- 2026-08-29 03:01:43
- Origin id
io.github.Blite-HQ/qnexus-mcp
README
# qnexus-mcp
A community [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **Quantinuum Nexus**,
wrapping the official [`qnexus`](https://github.com/Quantinuum/qnexus) Python SDK so any MCP-speaking agent
(Claude Code, Cursor, VS Code, Codex, …) can inspect Nexus and, opt-in, run circuits on the free emulator.
> **Not affiliated with, endorsed by, or an official product of Quantinuum.** "Quantinuum" and "Nexus" are
> trademarks of their respective owners, used here nominatively to describe compatibility.
<!-- mcp-name: io.github.Blite-HQ/qnexus-mcp -->
## Status
Early development. **Read-only by default.** Design and rationale live in
[`docs/DESIGN.md`](docs/DESIGN.md); the research behind it is in [`docs/research/`](docs/research/).
## Requirements
- Python 3.10+ and [`uv`](https://docs.astral.sh/uv/) (the `uvx` command). On Windows, note the
full path to `uvx.exe` (`where uvx` in a terminal) — GUI clients don't inherit your shell PATH.
- A [Quantinuum Nexus](https://nexus.quantinuum.com) account.
## 1. Authenticate (once)
`qnexus-mcp` **never handles your Nexus token.** Authenticate out-of-band with the `qnexus` CLI
(it opens your browser):
```bash
uvx --from qnexus qnx login
```
Inside Nexus JupyterHub, authentication is automatic; do not run `qnx login` there.
## 2. Add the server to your MCP client
The launch command is the same everywhere — only the config file differs per client:
```
uvx qnexus-mcp==0.2.0 # read-only (default)
uvx qnexus-mcp==0.2.0 --toolsets read,execute # + run circuits on the free H2-1LE emulator
```
**Pin a version** (`==0.2.0`): `uvx` otherwise resolves the latest PyPI release on every launch —
unpinned installs are neither reproducible nor auditable. Avoid `0.1.0` on Windows: its first
tool call hangs (fixed in 0.2.0).
> **What to expect on startup:** the first ever launch downloads the quantum SDK stack (1–3 min);
> every launch takes ~30 s before the server responds — the SDK is imported up front, before the
> MCP handshake. "Waiting for server to respond to `initialize`" during that window is normal.
### Claude Desktop
Settings → Developer → Local MCP servers → **Edit Config** (always use this button — the
Microsoft Store build keeps the file under `%LOCALAPPDATA%\Packages\Claude_*\...`, **not**
`%APPDATA%\Claude`), then add:
```jsonc
{
"mcpServers": {
"nexus": {
"command": "C:\\Users\\<you>\\.local\\bin\\uvx.exe", // or plain "uvx" on macOS/Linux
"args": ["qnexus-mcp==0.2.0", "--toolsets", "read,execute"]
}
}
}
```
Then **quit Claude Desktop fully and reopen** — the config is only read at cold start, and
closing the window leaves the old process running (tray icon → Quit, or
`taskkill /F /IM claude.exe`).
### VS Code
Command Palette → `MCP: Open User Configuration` (or a workspace `.vscode/mcp.json`):
```jsonc
{
"servers": {
"nexus": {
"type": "stdio",
"command": "C:\\Users\\<you>\\.local\\bin\\uvx.exe", // or plain "uvx" on macOS/Linux
"args": ["qnexus-mcp==0.2.0", "--toolsets", "read,execute"]
}
}
}
```
### Claude Code
```bash
claude mcp add nexus -- uvx qnexus-mcp==0.2.0 --toolsets read,execute
```
### Other MCP clients (Cursor, Codex, …)
Same command; the config shape is one of the two JSON forms above (`mcpServers` vs
`servers` + `"type": "stdio"`) — check your client's docs for which file to put it in.
Something not working? See [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) — it covers every
failure mode observed in real client setups (wrong config path, slow first start, auth, rate
limits, known Nexus-side errors).
## Configuration
| Flag | Env | Default | Effect |
|---|---|---|---|
| `--toolsets` | `QNEXUS_MCP_TOOLSETS` | `read` | Capability domains to expose (`read,execute,manage,destructive`) |
| `--allow-spend` | `QNEXUS_MCP_ALLOW_SPEND` | `false` | Permit credit-spending (HQC) execution |
| `--allow-hardware` | `QNEXUS_MCP_ALLOW_HARDWARE` | `false` | Permit real-QPU targets |
| `--allow-destructive` | `QNEXUS_MCP_ALLOW_DESTRUCTIVE` | `false` | Permit delete/cancel/archive |
| `--max-credits` | `QNEXUS_MCP_MAX_CREDITS` | `0` | Hard per-call HQC ceiling; `0` blocks all spend |
| `--max-outcomes` | `QNEXUS_MCP_MAX_OUTCOMES` | `100` | Top-N cap on distinct measurement outcomes returned per result (truncation is always reported) |
| `--max-submissions-per-minute` | `QNEXUS_MCP_MAX_SUBMISSIONS_PER_MINUTE` | `6` | Sliding-window submission cap; each circuit in a batch counts as one |
| `--projects` | `QNEXUS_MCP_PROJECTS` | *(all)* | Comma-separated project allowlist, enforced on every mutating tool |
## Safety
Read-only by default. Anything that spends credits or mutates cloud state requires an explicit opt-in flag
**and** an in-protocol confirmation, and the default execution backend is the free, noiseless `H2-1LE`
emulator. Submissions are rate-limited, cloud mutations are serialized, destructive project operations
resolve their target by **exact** name (never substring), and the server never reads, stores, or returns
your Nexus token. Every control is enforced server-side; MCP tool annotations are treated as UX hints
only. See [`docs/DESIGN.md`](docs/DESIGN.md) §6–§7.
**Prompt injection (conscious design decision).** Everything Nexus returns — job names, project names,
error messages, results — is attacker-influencable content (any Nexus user can name a job) and is treated
as untrusted data. There is no structural tagging that separates "data" from "instructions" in today's MCP
ecosystem; the structural boundary here is instead that **injected content cannot escalate**: every action
with consequences (spending credits, targeting hardware, deleting anything) requires launch flags the
agent cannot set *plus* an in-protocol human confirmation naming the exact target and cost. Injected text
can at worst confuse the agent's reasoning — it cannot spend or destroy anything on its own. This residual
risk is accepted and documented, not an omission.
**Governance.** This is an early-stage, single-maintainer project (see `CODEOWNERS`): releases are
published by one person via GitHub-OIDC Trusted Publishing (no long-lived PyPI tokens). Pin a version
(above) if that trust model matters for your deployment.
## Contributing
See [`CONTRIBUTING.md`](CONTRIBUTING.md). Contributions are accepted under the
[Developer Certificate of Origin](https://developercertificate.org/); sign off your commits with `-s`.
## License
Apache-2.0. See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).