Skip to content

Installation

Install from PyPI

pip install openquantum-mcp

This installs openquantum-mcp and its dependency openquantum-sdk.

Requires Python 3.10 or later (the official MCP Python library requires 3.10+).

Optional explicit install of both packages:

pip install openquantum-sdk openquantum-mcp

Verify

python -c "import openquantum_mcp; print(openquantum_mcp.__version__)"
python -m openquantum_mcp --version
python -m openquantum_mcp --help

These commands should print the package version and a short usage message, then exit. Do not start the server from a bare terminal for day-to-day use — it speaks MCP over stdio and is meant to be launched by an MCP client.

Confirm the console entry point is on your PATH (or use python -m openquantum_mcp in client config):

which openquantum-mcp || which python

Credentials

Create an SDK key in the portal: SDK Keys. See SDK Keys and Authentication.

Set one of:

export OPENQUANTUM_CLIENT_ID="s_..."
export OPENQUANTUM_CLIENT_SECRET="..."

or:

export OPENQUANTUM_SDK_KEY="/path/to/sdk-key.json"

The JSON key file must contain client_id and client_secret. If OPENQUANTUM_SDK_KEY is set but the path does not exist, the server fails with a clear error (it does not silently fall back).

Warning

Never commit secrets to git or paste them into shared chats. Prefer environment variables or your MCP client's secret storage.

Optional environment variables

Variable Default Meaning
OPENQUANTUM_MCP_MAX_CREDITS 10 Reject jobs whose estimated cost exceeds this many credits
OPENQUANTUM_MCP_WAIT_TIMEOUT_SECONDS 600 Default timeout for wait_for_job when timeout_seconds is omitted
OPENQUANTUM_MCP_POLL_INTERVAL_SECONDS 5 Default poll interval for wait_for_job when omitted
OPENQUANTUM_MCP_PREP_TIMEOUT_SECONDS 300 Max time to wait for job preparation to finish
OPENQUANTUM_MCP_DEFAULT_SHOTS 128 Default shots when prepare_job / submit_job omit shots
OPENQUANTUM_MCP_DEFAULT_SUBCATEGORY oth:oth Default job_subcategory_id when omitted
OPENQUANTUM_MCP_MAX_RESULT_RAW_CHARS 8000 Cap on raw result payload when include_raw=true
OPENQUANTUM_MCP_MAX_CALIBRATION_RAW_CHARS 8000 Cap on raw calibration payload
OPENQUANTUM_MANAGEMENT_BASE production management URL Override management API base (e.g. staging/dev)
OPENQUANTUM_SCHEDULER_BASE production scheduler URL Override scheduler API base
OPENQUANTUM_KEYCLOAK_BASE production id URL Override Keycloak / token base
OPENQUANTUM_KEYCLOAK_REALM platform Keycloak realm for client-credentials tokens

Auth variables (required; see Credentials):

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)

Next steps