ibm-quantum
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., "@ibm-quantum list my quantum backends then simulate a Bell pair with 1024 shots"
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.
IBM Quantum agent tools
A local MCP server that lets an AI agent use IBM Quantum through typed tools. It uses IBM's Qiskit Runtime SDK and the official MCP Python SDK. It can run from Codex or another MCP client that supports local stdio servers.
The API key stays in the original credential file. The server reads only its apikey field, keeps it in process memory, and sends it through IBM's authenticated SDK connection. Other JSON fields are ignored. No credential value is stored in source, tool arguments, tool responses, or the MCP configuration. Do not delete the credential file while this setup is in use.
Quick start without IBM credentials
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.lock
.venv/bin/python -m pip install --no-deps -e .
.venv/bin/python examples/mcp_client.pyOn Windows use .venv\Scripts\python.exe instead. Installation downloads dependencies; the example itself runs locally and submits no IBM job. For tests, install .[test] in the same environment and run python -m pytest -q with that environment's Python.
Related MCP server: mcp-qiskit
Local installation for IBM access
Python 3.11+ is required. With this folder in a permanent location, run:
python3 setup_local.py --api-key-file /absolute/path/to/apikey.json --register-codexThe script creates .venv, installs the pinned dependencies, generates .mcp.json with absolute paths, and registers ibm-quantum through codex mcp add. It prefers uv if available and otherwise uses Python's venv and pip. Omit --register-codex to generate configuration for another MCP client. Optional --instance CRN fixes the instance to use. Run setup again if you move the folder or credential file.
Start a new Codex task after registration. Example request:
Use the IBM Quantum tools to list my quantum computers, then simulate a Bell pair locally with 1024 shots.
For another MCP client, merge the generated .mcp.json entry into its MCP server configuration. Run python examples/mcp_client.py with this environment's Python for a working agent-side client example.
No Codex plugin manifest is included. The setup helper generates a local .mcp.json; rerun setup on a new machine. Direct MCP registration does not require a plugin marketplace entry. The server communicates over stdio and is not a public HTTP service.
Tools
Tool | Purpose |
| Inspect credential configuration presence and configured limits without authentication. |
| Authenticate and discover accessible IBM instances. |
| List QPUs, availability, qubit counts, and queue lengths. |
| Run a circuit locally, up to 20 qubits, without an IBM call. |
| Transpile a circuit for a selected QPU and inspect depth/gates. |
| Preview or submit a circuit and measure all qubits. |
| Preview or submit one weighted Pauli-sum expectation value. |
| List recent jobs, with pagination and pending-state filtering. |
| Read status and retrieve counts or expectation values. |
| Request cancellation of one unfinished job. |
When exactly one instance is accessible it is selected automatically. With multiple instances, pass an instance CRN returned by quantum_instances, or configure IBM_QUANTUM_INSTANCE. Backend names must come from discovery; available systems can change.
Circuit format
Pass JSON, not Python code. Indices start at zero and gate angles are numeric radians. Circuits contain up to 256 logical qubits and 10,000 gates. Supported gates are:
id x y z h s sdg t tdg sx sxdg
rx ry rz p u
cx cy cz ch swap ccx cswap
cp crx cry crz rxx ryy rzz barrierControl qubits precede target qubits. u takes three parameters, rotation/phase gates take one, and the other gates take none. Distinct gate qubits and argument counts are validated. barrier accepts one or more qubits. This initial version supports fully bound, unitary circuits with final measurements. It does not accept arbitrary Python, QASM files, dynamic control flow, reset, custom classical-register layouts, or parameter sweeps.
Call quantum_simulate with:
{
"circuit": {
"num_qubits": 2,
"gates": [
{"gate": "h", "qubits": [0]},
{"gate": "cx", "qubits": [0, 1]}
]
},
"shots": 1024,
"seed": 1234
}Counts use bitstrings with qubit 0 at the right. Sampler automatically measures every qubit into a register named meas. For quantum_run_estimator, supply observable, for example [{"pauli":"ZZ","coefficient":1.0}] for a two-qubit circuit. Pauli labels also place qubit 0 at the right. The tool maps observables to the transpiled physical-qubit layout.
Hardware workflow
Discover the instance and backend.
Simulate a small circuit locally.
Call
quantum_run_samplerorquantum_run_estimatorwith the circuit, backend, and defaultdry_run: trueto preview.When hardware execution is requested, repeat with
dry_run: false. This consumes IBM quantum usage and can incur charges under the selected plan.Keep the returned
job_id. Usequantum_jobto poll it and obtain results. Do not submit again while waiting. On an ambiguous submission error, inspectquantum_jobsand IBM's dashboard before retrying; there is no submission idempotency guarantee.
Default job limits are 8,192 sampler shots and 60 QPU execution seconds. The default requested shot count is 1,024. Estimator shots is the default per measurement configuration, so total estimator shots can be larger. The runtime limit caps quantum execution time; it is not a dollar budget, monthly budget, or queue timeout. These per-job limits do not restrict the number of jobs an agent may submit. The tool exposes mutation annotations to the client and defaults submission tools to preview, but client/user authorization remains the agent host's responsibility.
Server environment variable | Meaning |
| Path to an IBM JSON export containing |
| Alternative raw credential supplied by the process environment; takes precedence. |
| Optional default instance CRN. |
| Per-call shot setting ceiling; default 8192, maximum 1000000. |
| Per-job QPU execution ceiling; default 60, maximum 10800. |
If you lower the runtime ceiling below 60, also pass a corresponding max_execution_seconds to submission calls. Restart the server after changing credentials or environment configuration. Backend operational does not always mean a system is currently processing jobs; consult its status message.
quantum_job defaults to no queue wait. wait_seconds permits up to 30 seconds of SDK polling, separate from HTTP request/download timeouts. Results include at most 20 PUBs, the requested number of highest-count bitstrings (default 256), and at most 2,000 values in array fields. Truncation is reported. Parameter-sweep register shapes from jobs created elsewhere are reported without aggregating counts. For full results from large or externally created jobs, use the Qiskit Python API.
Validation
.venv/bin/python -m pip install 'pytest>=8,<9'
.venv/bin/python -m pytest tests -q
.venv/bin/python examples/mcp_client.pyTests use local simulation, fake IBM services, and a real MCP stdio subprocess. They do not use your API key or submit hardware jobs. No live IBM verification report is included, and this release review did not authenticate with IBM. See RELEASE_READINESS.md for the checks actually performed and remaining blockers.
References
SamplerV2 and EstimatorV2
Pinned to the maintained MCP 1.x API to keep FastMCP/ClientSession compatibility explicit. This is a local integration, not an IBM-endorsed product.
Status, provenance, and license
Experimental local integration, version 0.1.0. This repository began as a source-only preservation snapshot on 2026-10-29 of an AI-assisted local project. Original development history and live-service evidence were not imported. The retained snapshot is not evidence of independent authorship, scientific validation, or hardware performance. There are no bundled datasets, model weights, or credentials.
This project is distributed under the MIT License, added with owner authorization on 2026-10-29. The owner stated that all project code was created by AI and authorized MIT licensing. This records the owner’s assertion and permission, not an independent determination of copyright ownership or third-party provenance. Dependencies retain their own licenses; dependency pins do not establish ownership of this project. IBM and Qiskit names identify the service and SDKs used; this project is not endorsed by IBM.
Preview/transpilation still needs IBM access to retrieve backend information. Only configuration inspection and local simulation work without credentials. Per-job execution and shot ceilings are not a global spend cap: repeated submissions can accumulate usage and charges. Keep authorization controls in the MCP host. Review tool output before sharing it, since discovered instance names, CRNs, and job metadata can identify account resources.
See the release checklist before changing repository visibility.
Available Tools
10 toolsquantum_backendsBRead-onlyIdempotent
List accessible QPUs, availability, queue lengths, qubits, and supported gates for an instance.
Inputs: instance, min_num_qubits. Returns: object
quantum_cancel_jobADestructiveIdempotent
Request cancellation of the specified unfinished IBM job. Already consumed QPU time remains consumed.
Inputs: job_id (required), instance. Returns: object
quantum_configurationARead-onlyIdempotent
Show credential presence and configured limits without reading or returning the API key.
Inputs: no named parameters. Returns: object
quantum_instancesARead-onlyIdempotent
Authenticate with IBM and list accessible instance CRNs, names, and plans; no compute is submitted.
Inputs: no named parameters. Returns: object
quantum_jobARead-onlyIdempotent
Read job status and results. Default does not wait for queued work. Results include up to 20 PUBs, register counts or expectation values; large results are explicitly marked truncated.
Inputs: job_id (required), instance, max_counts, wait_seconds, +1 more. Returns: object
quantum_jobsARead-onlyIdempotent
List recent jobs for an instance. Page with skip. Use after ambiguous submission errors to avoid duplicates.
Inputs: skip, limit, pending, instance. Returns: object
quantum_previewARead-onlyIdempotent
Transpile for a specific IBM backend and report depth/gate counts without submitting a job.
Inputs: circuit (required), backend_name (required), instance, measured. Returns: object
quantum_run_estimatorA
Estimate one weighted Pauli-sum observable. Pauli rightmost character is qubit 0. Shots is per measurement configuration, not total shots. False submits hardware work; default previews only.
Inputs: circuit (required), observable (required), backend_name (required), shots, +3 more. Returns: object
quantum_run_samplerA
Sample a circuit, measuring all qubits. Default dry_run previews only. False submits one quota-consuming job and returns its ID immediately.
Inputs: circuit (required), backend_name (required), shots, dry_run, +2 more. Returns: object
quantum_simulateARead-onlyIdempotent
Simulate up to 20 qubits locally without IBM authentication or charges. Measure every qubit at end.
Inputs: circuit (required), seed, shots. 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
Most tools target distinct stages of the quantum workflow (config, discovery, preview, submit, monitor), but the pair quantum_job (read one job) and quantum_jobs (list jobs) differ only by a trailing 's', which is a real misselection hazard. quantum_preview also overlaps conceptually with the dry-run defaults of quantum_run_sampler/quantum_run_estimator, though descriptions distinguish them.
All names share a consistent quantum_ snake_case prefix, giving a predictable namespace. However, the set mixes noun-only names (quantum_configuration, quantum_backends, quantum_instances) with verb_noun names (quantum_cancel_job, quantum_run_sampler) and relies on singular/plural to distinguish get vs list.
Ten tools is well within the ideal range and each maps to a genuine step: credentials, instance/backend discovery, local simulation, transpile preview, sampler and estimator submission, job listing, job read, and cancellation. No tool feels redundant or vestigial.
The surface covers the full submit-preview-monitor-cancel lifecycle plus local simulation and discovery, which is strong coverage for a quantum backend client. Minor gaps remain: no session/batch management, no job deletion or log retrieval, and no tool to validate or build circuits before preview.
Maintenance
Related MCP Connectors
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
MCP-first toolbox for agents: KV storage, auth, queue, and utility tools. Free in early access.
Discover and call AI agents via MCP. Supports A2A agents and platform agents with async tasks.
Automate 1,000+ services from any MCP-compatible AI agent: build Applets, run actions and queries.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to create, validate, evaluate, and score quantum circuits with support for multiple hardware platforms. Provides tools for generating quantum algorithms (Bell states, Grover's, VQE), simulating circuits, checking hardware compatibility, and assessing circuit quality metrics.MIT
- 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.39 PyPIMIT
- FlicenseNot gradedqualityDmaintenanceEnables file system operations, web scraping, and AI-powered search through MCP tools for use by LLM agents.1-
- FlicenseAqualityDmaintenanceExposes two MCP tools (discover and execute) that enable agents to query an OpenAPI schema via natural language and execute matched API operations.2-