mcp-qiskit

mcp-qiskit

Model Context Protocol を通じて Qiskit 2.3.1 の量子コンピューティング機能を公開する MCP サーバーです。標準化された MCP ツールとリソースを介して、LLM が量子回路を作成、操作、実行できるようにします。

mcp-name: io.github.daedalus/mcp-qiskit

概要

このプロジェクトは、Qiskit の量子コンピューティング機能を大規模言語モデル（LLM）に公開する Model Context Protocol（MCP）サーバーを提供します。AI アシスタントは次のことができます。

• 量子回路の作成と操作
• 量子シミュレーターまたは実際のバックエンドでの回路の実行
• 回路の特性（深さ、ゲート、操作）の分析
• さまざまな形式での回路の可視化
• 量子バックエンドの管理

このツールを使う理由

• LLM との統合：外部ツールを使わずに、AI アシスタントが量子コンピューティングのタスクを実行できます
• 標準化されたインターフェース：MCP により、量子操作のための一貫したツールベースのインターフェースが提供されます
• Qiskit 2.3.1 との互換性：すべての機能を備えた Qiskit 2.3.1 向けに特化して設計されています
• 拡張可能：新しいツールやバックエンドを簡単に追加できます

インストール

前提条件

• Python 3.11 以降
• Qiskit 2.3.1
• 実行中の MCP クライアント（Claude Desktop、Cursor など）

PyPI からインストール

pip install mcp-qiskit[qiskit]

[qiskit] エクストラを指定すると、必要な Qiskit 依存関係がインストールされます。ほかに利用可能なエクストラ：

# Install with development dependencies
pip install mcp-qiskit[dev,test]

# Install with MCP server dependencies
pip install mcp-qiskit[mcp]

ソースからインストール

git clone https://github.com/daedalus/mcp-qiskit.git
cd mcp-qiskit
pip install -e ".[all]"

クイックスタート

Python ライブラリとして

from mcp_qiskit import create_quantum_circuit, add_gate, add_gates, add_measurement, run_circuit

# Create a 2-qubit circuit with 2 classical bits
circuit = create_quantum_circuit(2, 2)

# Apply a Hadamard gate on qubit 0
circuit = add_gate(circuit, "h", [0])

# Apply CNOT gate (control: qubit 0, target: qubit 1)
circuit = add_gate(circuit, "cx", [0, 1])

# Or add multiple gates at once with add_gates
circuit = add_gates(circuit, [
    {"gate": "h", "qubits": [0]},
    {"gate": "cx", "qubits": [0, 1]},
])

# Measure all qubits
circuit = add_measurement(circuit, [0, 1])

# Execute on Aer simulator
result = run_circuit(circuit, "aer_simulator", shots=1024)
print(f"Measurement results: {result['counts']}")

MCP サーバーとして

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "mcp-qiskit": {
      "command": "mcp-qiskit",
      "env": {}
    }
  }
}

Cursor

MCP サーバーの Cursor 設定に追加します。

{
  "mcpServers": {
    "mcp-qiskit": {
      "command": "mcp-qiskit",
      "args": []
    }
  }
}

その他の MCP クライアント

# Run as stdio server
mcp-qiskit

# Or use the Python module directly
python -m mcp_qiskit

MCP ツールのリファレンス

回路作成ツール

create_quantum_circuit_tool

指定した数の量子ビットと古典ビットを持つ、空の量子回路を作成します。

パラメーター：

• num_qubits (int)：量子ビット数
• num_classical_bits (int)：測定用の古典ビット数

戻り値： 回路を表す辞書

例：

circuit = create_quantum_circuit_tool(num_qubits=3, num_classical_bits=3)
# Returns: {"num_qubits": 3, "num_clbits": 3, "operations": [], "name": "circuit"}

add_gate_tool

回路に量子ゲートを追加します。このツールは呼び出しの間、回路の状態を維持します。

パラメーター：

• circuit (dict, optional)：変更する回路です。None の場合、8 量子ビットと 8 古典ビットを持つ回路が自動的に新規作成されます。
• gate_name (str)：ゲート名（例：「h」、「x」、「cx」、「rx」）
• qubits (list[int])：ゲートを適用する量子ビットのインデックスのリストです。単一の量子ビット（例：[0]）または複数の量子ビット（例：[0, 1, 2, 3]）を指定できます。単一量子ビットゲートに複数の量子ビットを指定すると、各量子ビットにゲートが適用されます。
• params (list[float], optional)：パラメーター付きゲートのパラメーター

サポートされているゲート：

• 単一量子ビット：h、x、y、z、s、t、sdg、tdg、i、id
• パラメーター付き：rx、ry、rz、u1、u2、u3、p
• 複数量子ビット：cx、cy、cz、swap
• 複数制御：mcx、mct、mcp、ccx、toffoli、c3x、c3sx、c4x
• 特殊：rxx、ryy、rzz、ch、cswap、cu、crx、cry、crz

状態を維持するパターン： 状態を維持するには、前回の呼び出しで返された回路を必ず渡します。

# Option 1: Pass circuit explicitly
circuit = add_gate_tool(circuit=None, gate_name="h", qubits=[0])  # Creates new circuit
circuit = add_gate_tool(circuit=circuit, gate_name="x", qubits=[1])  # Appends

# Option 2: Use returned circuit
circuit = add_gate_tool(None, "h", [0])
circuit = add_gate_tool(circuit, "cx", [0, 1])
circuit = add_gate_tool(circuit, "rx", [0], [0.5])

複数の量子ビットへの単一量子ビットゲートの適用： h、x、y、z などの単一量子ビットゲートを一度に複数の量子ビットに適用する場合は、量子ビットのインデックスのリストを使用します。

# Apply H gate to qubits 0, 1, 2, 3 simultaneously
circuit = add_gate_tool(circuit, "h", [0, 1, 2, 3])

# Apply X gate to qubits 4, 5, 6, 7 simultaneously  
circuit = add_gate_tool(circuit, "x", [4, 5, 6, 7])

add_gates_tool

1 回の呼び出しで、複数の量子ゲートを回路に追加します。このツールは呼び出し間で回路の状態を保持し、必要なツール呼び出しの数を減らします。

パラメーター：

• circuit (dict, optional)：変更する回路です。None の場合、8 量子ビットと 8 古典ビットを持つ新しい回路を自動的に作成します。
• gates (list[dict])：各ゲートの指定を含むリストです。各項目には次の内容が含まれます。
  • gate (str)：ゲート名（例：「h」、「x」、「cx」、「rx」）
  • qubits (list[int])：ゲートを適用する量子ビットのインデックス
  • params (list[float], optional)：パラメーター化ゲートのパラメーター

例：

# Add multiple gates in one call (reduces tool calls)
gates = [
    {"gate": "h", "qubits": [0]},
    {"gate": "cx", "qubits": [0, 1]},
    {"gate": "x", "qubits": [2]},
]
circuit = add_gates_tool(circuit=None, gates=gates)

# Can be chained to maintain state
circuit = add_gates_tool(None, [{"gate": "h", "qubits": [0, 1]}])
circuit = add_gates_tool(circuit, [{"gate": "rz", "qubits": [0], "params": [0.5]}])

add_measurement_tool

量子ビットに測定操作を追加します。このツールは呼び出し間で回路の状態を保持します。

パラメーター：

• circuit (dict, optional)：変更する回路です。None の場合、8 量子ビットと 8 古典ビットを持つ新しい回路を自動的に作成します。
• qubits (list[int])：測定する量子ビットのインデックス
• clbits (list[int], optional)：結果を格納する古典ビットのインデックス

例：

# Maintain state between calls
circuit = add_measurement_tool(circuit=None, qubits=[0, 1])           # Creates new circuit
circuit = add_measurement_tool(circuit=circuit, qubits=[2])          # Appends measurement

# Or use returned circuit
circuit = add_measurement_tool(None, [0, 1])           # Measure q0->c0, q1->c1
circuit = add_measurement_tool(circuit, [0, 1], [1, 0]) # Measure q0->c1, q1->c0

解析ツール

get_circuit_depth_tool

回路の深さ（レイヤー数）を返します。

パラメーター：

• circuit (dict)：解析する回路

戻り値： 回路の深さを表す整数

list_available_gates_tool

Qiskit で利用可能なすべての量子ゲートを一覧表示します。

戻り値： ゲート名の文字列のリスト

get_gate_definition_tool

量子ゲートの詳細情報を取得します。

パラメーター：

• gate_name (str)：ゲート名

戻り値： ゲートのプロパティを含む辞書：

• name：ゲート名
• num_qubits：ゲートが作用する量子ビット数
• num_parameters：パラメーター数（固定ゲートの場合は 0）
• params：パラメーター値のリスト

可視化ツール

draw_circuit_tool

回路をさまざまな形式で描画します。

パラメーター：

• circuit (dict)：描画する回路
• output_format (str)：出力形式：「ascii」、「text」、「mpl」、「latex」

戻り値： 回路の文字列表現

出力例（ASCII）：

     ┌───┐
q_0: ┤ H ├──■──
     └───┘┌─┴─┐
q_1: ────┤ X ├
         └───┘
c: 2/═══════╪═══
         0   1

バックエンドツール

list_backends_tool

利用可能な量子バックエンドを一覧表示します。

パラメーター：

• filters (dict, optional)：フィルター条件（例：{"status": "ONLINE"}）

戻り値： バックエンド情報を含む辞書のリスト

get_backend_status_tool

バックエンドのステータス情報を取得します。

パラメーター：

• backend_name (str)：バックエンド名

戻り値： 次の内容を含む辞書：

• name：バックエンド名
• status：ステータス（ONLINE/OFFLINE）
• num_qubits：量子ビット数

get_backend_configuration_tool

バックエンドの詳細な設定を取得します。

パラメーター：

• backend_name (str)：バックエンド名

戻り値： 次の内容を含む辞書：

• name：バックエンド名
• num_qubits：量子ビット数
• coupling_map：量子ビットの接続関係（該当する場合）
• basis_gates：利用可能な基底ゲートのリスト
• max_shots：許可される最大ショット数

実行ツール

run_circuit_tool

単一の量子回路を実行します。

パラメーター：

• circuit (dict)：実行する回路
• backend_name (str, optional)：バックエンド名（デフォルト：「aer_simulator」）
• shots (int, optional)：測定ショット数（デフォルト：1024）
• seed (int, optional)：再現性を確保するための乱数シード

戻り値： 次の内容を含む辞書：

• status：「COMPLETED」またはエラーメッセージ
• backend：使用したバックエンド
• shots：ショット数
• counts：測定結果のカウント（shots > 0 の場合）
• statevector：状態ベクトル（shots=None の場合）
• time_taken：実行時間（秒）

例：

result = run_circuit_tool(circuit, "aer_simulator", shots=1000, seed=42)
# Returns: {"status": "COMPLETED", "counts": {"00": 512, "11": 488}, ...}

run_circuits_tool

複数の回路をバッチで実行します。

パラメーター：

• circuits (list[dict])：実行する回路のリスト
• backend_name (str, optional)：バックエンド名
• shots (int, optional)：ショット数
• seed (int, optional)：乱数シード

戻り値： 結果辞書のリスト

例：

circuits = [circuit1, circuit2, circuit3]
results = run_circuits_tool(circuits, shots=100)
# Returns list of 3 result dictionaries

transpile_circuit_tool

最適化または特定のバックエンド向けに回路をトランスパイルします。

パラメーター：

• circuit (dict)：トランスパイルする回路
• optimization_level (int, optional)：0～3（デフォルト：1）
• basis_gates (list[str], optional)：対象の基底ゲート

**戻り値：**トランスパイルされた回路の辞書

例：

transpiled = transpile_circuit_tool(circuit, optimization_level=2)

MCP リソース

resource://backends

利用可能な量子バックエンドの一覧を提供します。利用可能なプロバイダーに応じて動的に更新されます。

resource://gates

Qiskit で利用可能なすべての量子ゲートの一覧を提供します。

使用例

ベル状態を作成する

# Create 2-qubit circuit
circuit = create_quantum_circuit(2, 2)

# Create Bell state: |Φ+⟩ = (|00⟩ + |11⟩) / √2
circuit = add_gate(circuit, "h", [0])
circuit = add_gate(circuit, "cx", [0, 1])
circuit = add_measurement(circuit, [0, 1])

# Execute
result = run_circuit(circuit, "aer_simulator", shots=1000)
print(result["counts"])  # Approximately {"00": 500, "11": 500}

グローバーのアルゴリズムを実行する

def create_grover_circuit(num_qubits, iterations):
    circuit = create_quantum_circuit(num_qubits, num_qubits)
    
    # Initial superposition
    for i in range(num_qubits):
        circuit = add_gate(circuit, "h", [i])
    
    # Grover iterations
    for _ in range(iterations):
        # Oracle (marked state |11...1⟩)
        for i in range(num_qubits):
            circuit = add_gate(circuit, "x", [i])
        circuit = add_gate(circuit, "cx", list(range(num_qubits - 1)), [num_qubits - 1])
        for i in range(num_qubits):
            circuit = add_gate(circuit, "x", [i])
        
        # Diffusion operator
        for i in range(num_qubits):
            circuit = add_gate(circuit, "h", [i])
        for i in range(num_qubits):
            circuit = add_gate(circuit, "x", [i])
        circuit = add_gate(circuit, "cx", list(range(num_qubits - 1)), [num_qubits - 1])
        for i in range(num_qubits):
            circuit = add_gate(circuit, "x", [i])
        for i in range(num_qubits):
            circuit = add_gate(circuit, "h", [i])
    
    # Measurement
    circuit = add_measurement(circuit, list(range(num_qubits)))
    return circuit

circuit = create_grover_circuit(3, 1)
result = run_circuit(circuit, "aer_simulator", shots=1000)

回路を描画して解析する

circuit = create_quantum_circuit(2, 2)
circuit = add_gate(circuit, "h", [0])
circuit = add_gate(circuit, "cx", [0, 1])
circuit = add_measurement(circuit, [0, 1])

# Get depth
depth = get_circuit_depth(circuit)
print(f"Circuit depth: {depth}")

# List gates
gates = list_available_gates()
print(f"Available gates: {len(gates)}")

# Draw circuit
ascii_output = draw_circuit(circuit, "ascii")
print(ascii_output)

ショアのアルゴリズムを実行する

from mcp_qiskit import (
    create_quantum_circuit,
    add_gate,
    add_measurement,
    run_circuit,
)

def build_shor_circuit(N=15, a=2, n_count=8):
    """Build Shor's factoring circuit for N=15 using MCX gates."""
    n = N.bit_length()
    circuit = create_quantum_circuit(n_count + n, n_count)
    
    # Superposition on first register
    for i in range(n_count):
        circuit = add_gate(circuit, "h", [i])
    
    # Initialize second register to |1>
    circuit = add_gate(circuit, "x", [n_count])
    
    # Controlled modular exponentiation using MCX
    for i in range(n_count):
        power = pow(a, 2**i, N)
        for j in range(n):
            if (power >> j) & 1:
                circuit = add_gate(circuit, "mcx", [[i], [n_count + j]])
    
    # Inverse QFT (simplified)
    for i in range(n_count - 1, -1, -1):
        for j in range(i + 1, n_count):
            circuit = add_gate(circuit, "cp", [i, j], [3.14159 / (2 ** (j - i))])
        circuit = add_gate(circuit, "h", [i])
    
    # Measure first register
    circuit = add_measurement(circuit, list(range(n_count)))
    return circuit

# Run Shor's algorithm to factor 15
circuit = build_shor_circuit(N=15, a=2, n_count=8)
result = run_circuit(circuit, "aer_simulator", shots=1000)
print(f"Results: {result['counts']}")

因数の抽出を含む完全な実装については、examples/shor_example.py を参照してください。

MCP Qiskit ツールを使ったショアのアルゴリズム

MCP Qiskit サーバーのツールを使って、N=15 を因数分解するショアのアルゴリズム回路を構築します。

# Step 1: Create an 8-qubit circuit with 4 classical bits
circuit = create_quantum_circuit_tool(num_qubits=8, num_classical_bits=4)

# Step 2: Apply H gates to qubits 0-3 (superposition)
circuit = add_gate_tool(circuit=circuit, gate_name="h", qubits=[0, 1, 2, 3])

# Step 3: Apply X gates to qubits 4-7 (initialize to |1⟩)
circuit = add_gate_tool(circuit=circuit, gate_name="x", qubits=[4, 5, 6, 7])

# Step 4: Add modular exponentiation using CP gates
circuit = add_gate_tool(circuit=circuit, gate_name="cp", qubits=[0, 4], params=[3.14159/2])  # CP(π/2)
circuit = add_gate_tool(circuit=circuit, gate_name="cp", qubits=[1, 6], params=[3.14159/4])  # CP(π/4)
circuit = add_gate_tool(circuit=circuit, gate_name="cp", qubits=[2, 4], params=[3.14159])    # CP(π)
circuit = add_gate_tool(circuit=circuit, gate_name="cp", qubits=[3, 4], params=[3.14159])    # CP(π)

# Step 5: Apply inverse QFT using H and CP gates (reverse order)
# CP(π/4) on [2,3], CP(π/2) on [1,2], CP(π) on [0,1]
circuit = add_gate_tool(circuit=circuit, gate_name="cp", qubits=[2, 3], params=[3.14159/4])
circuit = add_gate_tool(circuit=circuit, gate_name="cp", qubits=[1, 2], params=[3.14159/2])
circuit = add_gate_tool(circuit=circuit, gate_name="cp", qubits=[0, 1], params=[3.14159])
# H gates in reverse order
circuit = add_gate_tool(circuit=circuit, gate_name="h", qubits=[3, 2, 1, 0])

# Step 6: Measure qubits 0-3
circuit = add_measurement_tool(circuit=circuit, qubits=[0, 1, 2, 3])

# Step 7: Run on aer_simulator
result = run_circuit_tool(circuit=circuit, backend_name="aer_simulator", shots=1024, seed=42)
print(f"Measurement results: {result['counts']}")

# Extract factors from the measurement result:
# 1. Compute the phase from measurement outcome
# 2. Find order r via continued fractions
# 3. Calculate gcd(a^(r/2) ± 1, N)
# Expected: Factorization of 15 = 3 × 5

アーキテクチャ

mcp-qiskit/
├── src/mcp_qiskit/
│   ├── __init__.py          # Package exports
│   ├── __main__.py          # CLI entry point
│   ├── _circuit.py           # Circuit operations
│   ├── _backend.py           # Backend management
│   ├── _execution.py         # Circuit execution
│   └── _mcp.py               # MCP server definition
├── tests/                    # Test suite
├── SPEC.md                   # Project specification
└── README.md                 # This file

モジュールの役割

• _circuit.py：量子回路の作成、ゲート、測定、可視化
• _backend.py：バックエンドの検出、ステータス、設定
• _execution.py：回路の実行、トランスパイル
• _mcp.py：FastMCP サーバーの定義、ツールの登録

要件

• Python 3.11+
• qiskit >= 2.3.1
• qiskit-aer >= 0.14.0
• fastmcp >= 2.0

開発

セットアップ

git clone https://github.com/daedalus/mcp-qiskit.git
cd mcp-qiskit
pip install -e ".[all]"

テストの実行

pytest -v

コード品質

# Format code
ruff format src/ tests/

# Lint
ruff check src/ tests/

# Type check
mypy src/

Pre-commit フック

pre-commit install

トラブルシューティング

API キーと認証情報

このパッケージは、次の 2 種類のバックエンドをサポートしています。

1. Aer Simulator（デフォルト）- ローカルで実行され、API キーは不要です
2. IBM Quantum - IBM Quantum API トークンが必要です

IBM Quantum バックエンドの使用

IBM Quantum バックエンドを使用するには、API トークンを指定する必要があります。

オプション 1：環境変数

export IBM_QUANTUM_TOKEN="your_api_token_here"

または、Python コード内で設定します。

import os
os.environ["IBM_QUANTUM_TOKEN"] = "your_api_token_here"

オプション 2：Qiskit で認証情報を保存する

from qiskit_ibm_provider import IBMProvider

# Save your account (only needs to be done once)
IBMProvider.save_account(token="your_api_token_here", overwrite=True)

# Now you can use IBM backends
from mcp_qiskit._backend import list_backends, get_backend

backends = list_backends()  # Will include IBM backends
backend = get_backend("ibm_qasm_simulator")  # Or specific IBM backend

IBM Quantum トークンの取得方法：

1. IBM Quantum でアカウントを作成します
2. Account > My Tokens に移動します
3. API トークンをコピーします

MCP サーバーの環境変数：

MCP サーバーとして実行する場合は、起動前に環境変数を設定します。

export IBM_QUANTUM_TOKEN="your_token"
mcp-qiskit

または、MCP クライアントの設定で指定します。

{
  "mcpServers": {
    "mcp-qiskit": {
      "command": "mcp-qiskit",
      "env": {
        "IBM_QUANTUM_TOKEN": "your_token_here"
      }
    }
  }
}

バックエンドが見つからない場合

「Backend not found」と表示される場合は、バックエンド名が正しいことを確認します。

# List available backends
backends = list_backends()
print([b["name"] for b in backends])

インポートエラー

Qiskit が正しくインストールされていることを確認します。

pip install qiskit==2.3.1 qiskit-aer

MCP 接続の問題

サーバーが実行中であることを確認します。

mcp-qiskit --help

ライセンス

MIT License - 詳細は LICENSE ファイルを参照してください。

貢献

貢献を歓迎します。GitHub で issue を作成するか、PR を送信してください。

関連プロジェクト

• Qiskit - 量子コンピューティング SDK
• FastMCP - MCP フレームワーク
• Model Context Protocol - プロトコル仕様