SUPERQUANTX MCP SERVER

Quantum tools for AI assistants

SuperQuantX ships a Model Context Protocol server so Claude Desktop, Cursor or any MCP client can build and run circuits, compare backends and run small machine learning and optimisation experiments. It speaks stdio and runs on simulators only by default.

superquantx · mcp server

$ uvx --from "superquantx[mcp]==0.3.0" superquantx-mcp

Runs the stdio server with uvx, no install step. The built-in simulator needs no extra SDK.

or inside a uv project

SHELL

$ uv add "superquantx[mcp]==0.3.0"
$ uv run superquantx-mcp  # stdio MCP server
# add Qiskit and PennyLane backends
$ uv add "superquantx[mcp,qiskit,pennylane]==0.3.0"

TOOLS

Six read-only tools

Every tool returns structured JSON with "ok": true or "ok": false plus an error object. Tools never raise, and they do not touch the filesystem.

list_backends

Every SuperQuantX backend with SDK install status, initialisation and a 2 qubit Bell smoke test. Status is working, not_installed, init_failed, execution_failed or wrong_results.

backend_versions

Installed versions of SuperQuantX, Python, numpy, scipy, scikit-learn, every quantum SDK and per-backend version info.

run_circuit

Run a circuit given as OpenQASM 2, OpenQASM 3 or a JSON gate list. Returns counts, probabilities, gate counts and timing.

bell_state_demo

Run the same Bell circuit on several backends and report how many shots are correlated (00 or 11).

qsvm_classify

Quantum kernel SVM on a toy dataset or your own data, with kernel diagnostics and an RBF SVM baseline on the same split.

qaoa_maxcut

QAOA for MaxCut on a small graph with a classical optimiser, checked against exact brute force.

CLIENT CONFIGURATION

Run it with uvx

Point Cursor, Claude Desktop or any MCP client at uvx. It fetches the pinned release into an isolated environment and starts the stdio server.

.cursor/mcp.json · simulator

JSON

1{
2  "mcpServers": {
3    "superquantx": {
4      "command": "uvx",
5      "args": ["--from", "superquantx[mcp]==0.3.0", "superquantx-mcp"]
6    }
7  }
8}

.cursor/mcp.json · with Qiskit and PennyLane

JSON

1{
2  "mcpServers": {
3    "superquantx": {
4      "command": "uvx",
5      "args": ["--from", "superquantx[mcp,qiskit,pennylane]==0.3.0", "superquantx-mcp"]
6    }
7  }
8}

LIMITS AND SAFETY

Capped inputs, hardware off

Defaults can be changed with environment variables but never above the hard ceiling. Passing a device to run_circuit is refused unless the server starts with SUPERQUANTX_MCP_ALLOW_HARDWARE=1, and the backend SDK's own credentials are still required.

MCP input limits
Variable	Default	Ceiling
SUPERQUANTX_MCP_MAX_QUBITS	10	16
SUPERQUANTX_MCP_MAX_SHOTS	10000	100000
SUPERQUANTX_MCP_MAX_GATES	500	2000
SUPERQUANTX_MCP_MAX_SAMPLES	80	200
SUPERQUANTX_MCP_MAX_FEATURES	4	6
SUPERQUANTX_MCP_MAX_QAOA_NODES	10	12

Full MCP guide