Skip to main content
Glama

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 (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 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 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:

{
  "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,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 — 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 §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

Apache-2.0. See LICENSE and NOTICE.

Available Tools

10 tools
nexus_auth_statusA
Read-onlyIdempotent

Report whether a valid Nexus session exists.

Inputs: no named parameters. Returns: object

nexus_device_statusA
Read-onlyIdempotent

Report whether a device is online. Emulators/syntax checkers are always available.

Inputs: device (required). Returns: object

nexus_get_quotaA
Read-onlyIdempotent

Return remaining compilation/simulation quotas.

Inputs: no named parameters. Returns: result

nexus_get_resultsA
Read-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_costA
Read-onlyIdempotent

Return the HQC cost of an existing job by id.

Inputs: job_id (required). Returns: object

nexus_job_statusA
Read-onlyIdempotent

Return the status of a job by id.

Inputs: job_id (required). Returns: object

nexus_list_devicesA
Read-onlyIdempotent

List available backends and their status.

Inputs: no named parameters. Returns: result

nexus_list_jobsA
Read-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_projectsA
Read-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_whoamiA
Read-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

    A4/5.0

    Scored across 10 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness2/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers