QPanda3 Runtime MCP Server

Python 3.10+ FastMCP License Documentation

A Model Context Protocol (MCP) server that enables AI assistants to interact with Origin Quantum computing services through QPanda3 Runtime.

Features

Account Management: Configure and manage Origin Quantum cloud account authentication
Device Management: List and query available QPU devices
Quantum Computing Tasks: Execute sampling and estimation tasks
Batch Operations: Run multiple circuits efficiently
Multi-Objective Decisions: CircuitObservableBinding for complex optimization
Task Management: Query task status, retrieve results, cancel tasks
Example Circuits: Provides common quantum circuit example resources

Documentation

Document	Description
English Docs	English documentation site
中文文档	Chinese documentation site
Getting Started	Complete beginner's guide - START HERE
Installation Guide	Detailed installation instructions
Quick Start	Fast setup for experienced users
Configuration	Environment and client configuration
User Guide	Detailed feature documentation
API Reference	Auto-generated API documentation

Installation

One-Click Setup (Recommended)

The project provides setup scripts that automate the entire process:

Linux / macOS:

git clone https://github.com/OriginQ/qpanda3-runtime-mcp-server.git
cd qpanda3-runtime-mcp-server
chmod +x scripts/setup_configure.sh
./scripts/setup_configure.sh

Windows (PowerShell):

git clone https://github.com/OriginQ/qpanda3-runtime-mcp-server.git
cd qpanda3-runtime-mcp-server
.\scripts\setup_configure.ps1

The script handles everything: dependency setup, API key configuration, and MCP client setup.

See Installation Guide for manual install options.

Quick Start

# 1. Configure your API key
cp .env.example .env
# Edit .env and set QPANDA3_API_KEY=your_api_key_here

# 2. Run the server
.venv/bin/python -m qpanda3_runtime_mcp_server       # Linux/macOS
# .venv\Scripts\python.exe -m qpanda3_runtime_mcp_server  # Windows

See Configuration for MCP client setup and advanced options.

MCP Tools

Account Management

Tool	Description
`setup_origin_quantum_account_tool`	Configure Origin Quantum cloud account authentication
`list_saved_accounts_tool`	List saved account information (session-based)
`active_account_info_tool`	Get currently active account information

Device Management

Tool	Description
`list_qpu_devices_tool`	List all available QPU (Quantum Processing Unit) devices
`get_qpu_properties_tool`	Get detailed properties of a specific QPU device

Quantum Computing Tasks

Tool	Description
`sample_tool`	Execute quantum circuit sampling task on a QPU device
`estimate_tool`	Execute expectation estimation task for a quantum circuit
`batch_sample_tool`	Batch execute multiple quantum circuit sampling tasks
`batch_estimate_tool`	Batch execute estimation tasks for multiple circuits with one observable

Multi-Objective Decision (CircuitObservableBinding)

Tool	Description
`create_circuit_observable_binding_tool`	Create a binding for multiple circuits and observables
`add_product_rule_tool`	Add Cartesian product combination rule (all combinations)
`add_zip_rule_tool`	Add one-to-one combination rule (paired combinations)
`estimate_with_binding_tool`	Execute estimation using the created binding
`list_bindings_tool`	List all stored CircuitObservableBinding objects
`delete_binding_tool`	Delete a stored CircuitObservableBinding object

Task Management

Tool	Description
`get_task_status_tool`	Get the execution status of a task (`PENDING`/`RUNNING`/`DONE`/`FAILED`/`CANCELLED`)
`get_task_results_tool`	Get the computation results of a completed task
`cancel_task_tool`	Cancel a running or pending task
`list_my_tasks_tool`	List user's recent quantum computing tasks

MCP Resources

Resource URI	Description
`qpanda://status`	Service status
`circuits://bell-state`	Bell state circuit example
`circuits://ghz-state`	GHZ state circuit example
`circuits://random`	Random number generator circuit
`circuits://superposition`	Superposition circuit example

Example Usage

Configure Account

# Auto-configure via environment variables
# Or call explicitly
await setup_origin_quantum_account_tool(
    api_key="your_api_key"
)

List Devices

devices = await list_qpu_devices_tool()
print(f"Available devices: {devices['total_devices']}")

Execute Sampling Task

# Bell state circuit
circuit = """QINIT 2
CREG 2
H q[0]
CNOT q[0],q[1]
MEASURE q[0],c[0]
MEASURE q[1],c[1]"""

result = await sample_tool(
    circuit=circuit,
    device_id="20",
    shots=1000
)
task_id = result["task_id"]

# Check status and get results
status = await get_task_status_tool(task_id)
if status["task_status"] == "DONE":
    results = await get_task_results_tool(task_id)
    print(f"Measurement results: {results['results']}")

Configure in AI Coding Platforms

Auto-configure: Use ./scripts/setup_configure.sh --mcp claude-desktop (or --mcp cline, --mcp cursor, etc.)

All clients use the same config format (replace /path/to/... with your actual path):

{
  "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_here" }
    }
  }
}

Client	Config File Location
Claude Code	`~/.claude.json`
Claude Desktop	macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
Cline	`~/.vscode-server/data/User/globalStorage/saoudrizwan.cline/settings/cline_mcp_settings.json`
Cursor	`.cursor/mcp.json` (project root)
Windsurf	`~/.codeium/windsurf/mcp_config.json`

For more clients (Trae etc.), see Configuration Guide.

Development

Install Development Dependencies

uv sync --extra dev --extra test

Run Tests

uv run pytest

Code Linting

uv run ruff check .
uv run mypy src/

Build Documentation

# Install documentation dependencies
uv sync --extra docs

# Build documentation (English + Chinese)
./scripts/build-docs.sh

# Local preview with live reload (language switching supported)
mkdocs serve

Project Structure

qpanda3-runtime-mcp-server/
├── src/
│   └── qpanda3_runtime_mcp_server/
│       ├── __init__.py          # Package entry point
│       ├── server.py            # MCP server definition
│       ├── runtime.py           # QPanda3 Runtime core logic
│       └── utils.py             # Utility functions
├── scripts/
│   ├── setup_configure.sh       # One-click setup (Linux/macOS)
│   ├── setup_configure.ps1      # One-click setup (Windows PowerShell)
│   ├── setup_configure.bat      # One-click setup (Windows CMD)
│   ├── build-docs.sh            # Build all documentation
│   └── serve-docs.sh            # Serve docs with live reload
├── tests/
│   ├── __init__.py
│   ├── conftest.py              # pytest configuration
│   ├── test_server.py           # Server tests
│   └── test_runtime.py          # Runtime tests
├── docs/
│   ├── *.md                     # English documentation (default)
│   └── cn/                      # Chinese documentation
├── mkdocs.yml                   # MkDocs configuration (i18n)
├── .github/
│   └── workflows/               # GitHub Actions workflows
├── pyproject.toml               # Project configuration
├── README.md                    # Project documentation
├── LICENSE                      # Apache 2.0 License
├── .env.example                 # Environment variable example
└── .gitignore                   # Git ignore file

Notes

Default Server: The server connects to https://qpanda3-runtime.qpanda.cn by default. Set QPANDA3_SERVER_URL to override.
Channel: The server uses the qcloud channel by default
Async Support: All tool functions are async functions
Error Handling: All functions return dictionaries containing a status field
Type Hints: Python type hints are used for better code readability

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Contributing

See Contributing Guide for details.

Changelog

See Changelog for version history.