Skip to main content

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.4.0 (openquantum_mcp.__version__). It depends on openquantum-sdk>=1.2.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 100 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. get_backend returns configuration_options for that QPU or simulator
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.

Call get_backend before preparing. Pass required configuration_options in configuration_data (choice value, not title). The server writes shots into that object and leaves schema defaults unset. visible_when is empty when a field always applies. Otherwise include the field only when every entry matches. Simulators require shots and engine. configuration_data on submit_job applies to the one-shot path. A preparation_id already carries its configuration.

Security: file_path is read by the MCP process and uploaded; prefer qasm strings when possible and least-privilege process accounts.

Spend policy

  1. Estimated cost greater than 10 credits (configurable) → rejected.
  2. Cost 0 → allowed.
  3. Public plan and Spark ≥ cost → auto-approved.
  4. Spend that would use Full credits → requires confirm_spend=true.

Default job subcategory: oth:oth. Jobs are tagged submitted_with=mcp.

Example agent flow

  1. list_backends / get_credits
  2. prepare_job with OpenQASM → review quote
  3. submit_job (with confirm_spend=true when required)
  4. wait_for_job (re-call if still queued; QPU queues can be long)
  5. get_job_results
  6. get_job_calibration only if needed

License

Apache-2.0

Metadata

Release files for openquantum-mcp 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for openquantum-mcp 0.4.0
File Size Uploaded Provenance Actions
openquantum_mcp-0.4.0.tar.gz 32.7 kB Without provenance Details for openquantum_mcp-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for openquantum-mcp 0.4.0
File Interpreter ABI Platform Actions
openquantum_mcp-0.4.0-py3-none-any.whl Python 3 none any Details for openquantum_mcp-0.4.0-py3-none-any.whl

Total release size: 59.8 kB

Release files / openquantum_mcp-0.4.0.tar.gz

Download URL openquantum_mcp-0.4.0.tar.gz
Size 32.7 kB
Tags Source
SHA-256 checksum
How to use checksums
bee2a0885eac957aa0c5f92a1099282d7f2a4edd7353f2870dd2873660227aa7
BLAKE2b-256 checksum
How to use checksums
8ff971114183507dfb70b6001f15f4809a23c24d612ea60337fd9d9cad9ecd86
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / openquantum_mcp-0.4.0-py3-none-any.whl

Download URL openquantum_mcp-0.4.0-py3-none-any.whl
Size 27.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9682dbe38f0338cef95167953819571a21fe1da07ba48643d6bebb74697a4f80
BLAKE2b-256 checksum
How to use checksums
aa21058a7fd0b22f40d71363790e5682f3f619ebf5c0da45cb6d3508518156ae
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for openquantum-mcp 0.4.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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page