Quick Start

April 16, 2026 · View on GitHub

This guide will help you get started with the QPanda3 Runtime MCP Server quickly.

New to quantum computing or MCP? Check out our comprehensive Getting Started Guide for a complete beginner's walkthrough with detailed explanations.

One-Click Setup

The fastest way to get started is using the setup scripts. See Configuration for the full CLI reference.

# Linux / macOS — minimal (non-interactive)
./scripts/setup_configure.sh

# Windows PowerShell — minimal (non-interactive)
.\scripts\setup_configure.ps1

For a fully automated setup with your API key and MCP client configured in one command:

# Linux / macOS — one-line full setup
./scripts/setup_configure.sh --api-key YOUR_KEY --mcp claude-desktop

# Windows PowerShell — one-line full setup
.\scripts\setup_configure.ps1 -ApiKey "YOUR_KEY" -McpClient claude-desktop

To be guided through each step interactively:

# Linux / macOS
./scripts/setup_configure.sh --interactive

# Windows PowerShell
.\scripts\setup_configure.ps1 -Interactive

Prerequisites

RequirementDescription
Python 3.10+Python interpreter (up to 3.13)
Origin Quantum AccountAPI key
MCP-compatible AI AssistantClaude Desktop, Cline, or similar

Basic Usage

1. Set Up Credentials

Copy the example file and edit it:

cp .env.example .env
# Then edit .env with your API key

Or use environment variables:

export QPANDA3_API_KEY="your_api_key_here"

2. Run the Server

python -m qpanda3_runtime_mcp_server

Common Tasks

Setting Up Your Account

The first step is to configure your Origin Quantum account:

# Using the MCP tool
await setup_origin_quantum_account_tool(
    api_key="your_api_key"
)

Listing Available Devices

To see what quantum devices are available:

devices = await list_qpu_devices_tool()
for device in devices["devices"]:
    print(f"Device: {device['name']} (ID: {device['id']})")
    print(f"  Qubits: {device['num_qubits']}")
    print(f"  Operational: {device['operational']}")

Running a Quantum Circuit

Here's how to run a Bell state circuit:

# Define the circuit in OriginIR format
circuit = """QINIT 2
CREG 2
H q[0]
CNOT q[0],q[1]
MEASURE q[0],c[0]
MEASURE q[1],c[1]"""

# Submit the sampling task
result = await sample_tool(
    circuit=circuit,
    device_id="20",
    shots=1000
)

task_id = result["task_id"]
print(f"Task submitted: {task_id}")

# Check task status
status = await get_task_status_tool(task_id)
print(f"Status: {status['task_status']}")

# Get results when done
if status["task_status"] == "DONE":
    results = await get_task_results_tool(task_id)
    print(f"Results: {results['results']}")

Running Expectation Estimation

To estimate the expectation value of an observable:

# Define circuit (without measurements)
circuit = """QINIT 2
CREG 2
H q[0]
CNOT q[0],q[1]"""

# Define observable
observable = {"Z0 Z1": 1.0}

# Submit estimation task
result = await estimate_tool(
    circuit=circuit,
    observable=observable,
    device_id="20"
)

task_id = result["task_id"]

Using with AI Assistants

Cline Configuration

Add the following to your Cline MCP settings:

{
  "mcpServers": {
    "qpanda3-runtime": {
      "command": "/path/to/qpanda3-runtime-mcp-server/.venv/bin/python",
      "args": ["-m", "qpanda3_runtime_mcp_server"],
      "cwd": "/path/to/qpanda3-runtime-mcp-server",
      "env": {
        "QPANDA3_API_KEY": "your_api_key"
      },
      "disabled": false
    }
  }
}

Example Prompts

Once connected, you can ask your AI assistant:

  • "List all available QPU devices"
  • "Get properties of device ID 20"
  • "Run a Bell state circuit on device 20 with 1000 shots"
  • "Check the status of my task"
  • "Show me an example quantum circuit"

Available Circuit Resources

The server provides pre-built quantum circuits:

Resource URIDescription
circuits://bell-stateBell state (2-qubit entanglement)
circuits://ghz-stateGHZ state (3-qubit entanglement)
circuits://randomQuantum random number generator
circuits://superpositionSingle qubit superposition

Next Steps