qnexus-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@qnexus-mcp What projects do I have on Nexus?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
qnexus-mcp
A community Model Context Protocol (MCP) server for Quantinuum Nexus,
wrapping the official 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.
Status
Early development. Read-only by default. Design and rationale live in
docs/DESIGN.md; the research behind it is in docs/research/.
Related MCP server: Qiskit MCP Server
Requirements
Python 3.10+ and
uv(theuvxcommand). On Windows, note the full path touvx.exe(where uvxin a terminal) — GUI clients don't inherit your shell PATH.A Quantinuum Nexus account.
1. Authenticate (once)
qnexus-mcp never handles your Nexus token. Authenticate out-of-band with the qnexus CLI
(it opens your browser):
uvx --from qnexus qnx loginInside 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 emulatorPin 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:
{
"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):
{
"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
claude mcp add nexus -- uvx qnexus-mcp==0.2.0 --toolsets read,executeOther 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 — 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 |
|
|
| Capability domains to expose ( |
|
|
| Permit credit-spending (HQC) execution |
|
|
| Permit real-QPU targets |
|
|
| Permit delete/cancel/archive |
|
|
| Hard per-call HQC ceiling; |
|
|
| Top-N cap on distinct measurement outcomes returned per result (truncation is always reported) |
|
|
| Sliding-window submission cap; each circuit in a batch counts as one |
|
| (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 §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. Contributions are accepted under the
Developer Certificate of Origin; sign off your commits with -s.
License
Available Tools
10 toolsnexus_auth_statusARead-onlyIdempotent
Report whether a valid Nexus session exists.
Inputs: no named parameters. Returns: object
nexus_device_statusARead-onlyIdempotent
Report whether a device is online. Emulators/syntax checkers are always available.
Inputs: device (required). Returns: object
nexus_get_quotaARead-onlyIdempotent
Return remaining compilation/simulation quotas.
Inputs: no named parameters. Returns: result
nexus_get_resultsARead-onlyIdempotent
Return measurement counts for a completed job by id.
Counts are capped at the top --max-outcomes outcomes by frequency; total_outcomes /
omitted_outcomes / omitted_shots report any truncation. Multi-circuit (batch) jobs return
one entry per circuit under items, in submission order.
Inputs: job_id (required). Returns: object
nexus_job_costARead-onlyIdempotent
Return the HQC cost of an existing job by id.
Inputs: job_id (required). Returns: object
nexus_job_statusARead-onlyIdempotent
Return the status of a job by id.
Inputs: job_id (required). Returns: object
nexus_list_devicesARead-onlyIdempotent
List available backends and their status.
Inputs: no named parameters. Returns: result
nexus_list_jobsARead-onlyIdempotent
List jobs visible to the user (one page of up to limit, plus the total count).
Optional filters: exact project name, status (e.g. COMPLETED, RUNNING, ERROR), and a
name_like substring. Occasionally returns a Nexus-side server error unrelated to your
request; if so, use nexus_job_status / nexus_get_results by id instead of retrying this call.
Inputs: limit, status, project, name_like. Returns: object
nexus_list_projectsARead-onlyIdempotent
List Nexus projects visible to the user (one page of up to limit, plus the total count).
Optional name_like substring filter; set archived to list archived projects instead.
Inputs: limit, archived, name_like. Returns: object
nexus_whoamiARead-onlyIdempotent
Return the authenticated Nexus user.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a distinct resource and action: auth status and whoami separate session validity from user identity; list_devices and device_status distinguish enumeration from specific status; job tools (list, status, cost, results) each serve a unique query purpose. No two tools overlap in what they retrieve.
All tools share the 'nexus_' prefix and mostly follow a verb_noun (list_devices, get_quota) or resource_status (job_status, device_status) pattern. The 'whoami' tool deviates slightly from the pattern, but the naming remains predictable and readable.
10 tools is a well-scoped count for a quantum computing platform, covering auth, devices, projects, quotas, and jobs without unnecessary bloat. Each tool earns its place for typical query workflows.
The set is heavily read-only, covering queries for auth, devices, projects, quotas, and job status/results, but lacks any tool to submit, cancel, or manage jobs or projects. This is a significant gap for a platform presumably intended to run quantum workloads, limiting agent capability.
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server exposing Qiskit quantum computing functionality through the Model Context Protocol. Enables LLMs to create, manipulate, and execute quantum circuits via standardized MCP tools and resources.MIT
- FlicenseAqualityDmaintenanceUnofficial Model Context Protocol (MCP) server that enables LLMs to build and execute quantum circuits using Qiskit.137-
- AlicenseNot gradedqualityCmaintenanceAn MCP server that gives AI agents direct control over QEMU virtual machines.25 npm1MIT

nexus-exchange-mcpofficial
AlicenseBqualityAmaintenanceAn MCP server that exposes the Nexus Exchange API as tools an AI agent can call to read market data and place trades.11523 npm3Apache 2.0