openquantum-mcp
Model Context Protocol (MCP) server for Open Quantum.
Any MCP-compatible client (Claude, Cursor, VS Code, Grok, and others) can discover backends, submit quantum jobs, wait for completion, and summarize results using your Open Quantum SDK credentials.
The server talks to the platform through OpenQuantumClient. Quote selection and job/preparation polling use the core SDK (choose_plan_and_priority, wait_for_preparation, wait_for_job). Auto plan selection still prefers Public so Spark credits can apply.
One stdio server, standard MCP tools — nothing client-specific in the package.
Docs: docs.openquantum.com/mcp
Install
pip install openquantum-sdk openquantum-mcp
Requires Python 3.10+. Current package version: 0.2.0 (openquantum_mcp.__version__). It depends on openquantum-sdk>=1.0.0 and installs that package if needed:
pip install openquantum-mcp
The sdist includes tests/ so the unit tests can be run from a source distribution. The wheel does not install them. scripts/ stays out of both.
Verify without starting the stdio server:
python -c "import openquantum_mcp; print(openquantum_mcp.__version__)"
python -m openquantum_mcp --version
python -m openquantum_mcp --help
Authentication
Use the same SDK key credentials as the Core SDK (portal SDK keys):
| Variable | Meaning |
|---|---|
OPENQUANTUM_CLIENT_ID |
SDK key client id |
OPENQUANTUM_CLIENT_SECRET |
SDK key secret |
OPENQUANTUM_SDK_KEY |
Path to JSON key file (client_id + client_secret) |
If OPENQUANTUM_SDK_KEY is set but the file is missing, startup/auth fails with a clear path error (no silent fallback).
Optional configuration:
| Variable | Default | Meaning |
|---|---|---|
OPENQUANTUM_MCP_MAX_CREDITS |
10 |
Hard cap on estimated credits per job |
OPENQUANTUM_MCP_WAIT_TIMEOUT_SECONDS |
600 |
Default wait_for_job timeout when the tool arg is omitted |
OPENQUANTUM_MCP_POLL_INTERVAL_SECONDS |
5 |
Default wait_for_job poll interval when omitted |
OPENQUANTUM_MCP_PREP_TIMEOUT_SECONDS |
300 |
Job preparation wait timeout |
OPENQUANTUM_MCP_DEFAULT_SHOTS |
128 |
Default shots when omitted |
OPENQUANTUM_MCP_DEFAULT_SUBCATEGORY |
oth:oth |
Default job subcategory |
OPENQUANTUM_MCP_MAX_RESULT_RAW_CHARS |
8000 |
Cap on raw result text |
OPENQUANTUM_MCP_MAX_CALIBRATION_RAW_CHARS |
8000 |
Cap on raw calibration text |
OPENQUANTUM_ORGANIZATION_ID |
first membership | Billing org when a tool omits organization_id |
OPENQUANTUM_MANAGEMENT_URL |
production | Override management API base URL |
OPENQUANTUM_SCHEDULER_URL |
production | Override scheduler API base URL |
OPENQUANTUM_KEYCLOAK_BASE |
production | Override Keycloak base URL |
OPENQUANTUM_KEYCLOAK_REALM |
platform |
Keycloak realm |
OPENQUANTUM_SCHEDULER_URL and OPENQUANTUM_MANAGEMENT_URL are the names shared with the other SDK surfaces. The older OPENQUANTUM_SCHEDULER_BASE and OPENQUANTUM_MANAGEMENT_BASE names still work when the *_URL variables are unset.
Run
export OPENQUANTUM_CLIENT_ID=...
export OPENQUANTUM_CLIENT_SECRET=...
python -m openquantum_mcp
# or
openquantum-mcp
MCP client configuration
Point your client at a Python environment where openquantum-mcp is installed, and pass credentials in the server env. Exact config file locations differ by host; the process definition is the same:
{
"mcpServers": {
"openquantum": {
"command": "python",
"args": ["-m", "openquantum_mcp"],
"env": {
"OPENQUANTUM_CLIENT_ID": "...",
"OPENQUANTUM_CLIENT_SECRET": "..."
}
}
}
}
Prefer an absolute path to python if the client does not inherit your shell PATH (for example, /path/to/venv/bin/python).
Tools
| Tool | Purpose |
|---|---|
list_organizations |
Organizations for the account |
get_credits |
Spark and Full credit balances |
list_backends / get_backend |
Discover devices |
list_job_categories |
Categories and subcategories |
prepare_job |
Upload circuit and return a quote (no spend) |
submit_job |
Create a job (does not wait for completion) |
get_job / list_jobs |
Job status |
wait_for_job |
Poll until terminal status or timeout |
get_job_results |
Compact output summary |
get_job_calibration |
Calibration data on demand |
cancel_job |
Cancel when allowed by platform rules |
prepare_job / submit_job accept execution_plan (auto / public / private / UUID) and queue_priority (auto / standard / priority / instant / UUID). Auto plan selection prefers Public so Spark can apply. Quotes include quote_summary with per-priority pricing.
Security: file_path is read by the MCP process and uploaded; prefer qasm strings when possible and least-privilege process accounts.
Spend policy
- Estimated cost greater than 10 credits (configurable) → rejected.
- Cost 0 → allowed.
- Public plan and Spark ≥ cost → auto-approved.
- Spend that would use Full credits → requires
confirm_spend=true.
Default job subcategory: oth:oth. Jobs are tagged submitted_with=mcp.
Example agent flow
list_backends/get_creditsprepare_jobwith OpenQASM → review quotesubmit_job(withconfirm_spend=truewhen required)wait_for_job(re-call if still queued; QPU queues can be long)get_job_resultsget_job_calibrationonly if needed
License
Apache-2.0
Metadata
Release files for openquantum-mcp 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| openquantum_mcp-0.2.0.tar.gz | 28.6 kB | Without provenance | Details for openquantum_mcp-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| openquantum_mcp-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for openquantum_mcp-0.2.0-py3-none-any.whl |
Total release size: 53.4 kB
Release files / openquantum_mcp-0.2.0.tar.gz
| Download URL | openquantum_mcp-0.2.0.tar.gz |
|---|---|
| Size | 28.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6e3835e4660f15f33d3b0a3dc149935f9d751c8490fd32720dc1420068fca5ff
|
|
BLAKE2b-256 checksum How to use checksums |
fcf689d45b16db3e363ddf57ec15a3ff41b829f277309e0dfa091ed8fc4ce1e0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / openquantum_mcp-0.2.0-py3-none-any.whl
| Download URL | openquantum_mcp-0.2.0-py3-none-any.whl |
|---|---|
| Size | 24.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8973ac5a120d85daabda89d0acb227109c4febda1684c89f2c85d34632226f4d
|
|
BLAKE2b-256 checksum How to use checksums |
b147f847934741debdc00186563292d1edb4dab6cbf2ad412dd14dd309190deb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for openquantum-mcp 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.