MCP Qiskit

mcp-qiskit

MCP server exposing Qiskit 2.3.1 quantum computing functionality through the Model Context Protocol. Enables LLMs to create, manipulate, and execute quantum circuits via standardized MCP tools and resources.

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

Overview

This project provides a Model Context Protocol (MCP) server that exposes Qiskit quantum computing functionality to Large Language Models (LLMs). It allows AI assistants to:

• Create and manipulate quantum circuits
• Execute circuits on quantum simulators or real backends
• Analyze circuit properties (depth, gates, operations)
• Visualize circuits in various formats
• Manage quantum backends

Why Use This?

• LLM Integration: Enables AI assistants to perform quantum computing tasks without external tooling
• Standardized Interface: MCP provides a consistent tool-based interface for quantum operations
• Qiskit 2.3.1 Compatible: Specifically designed for Qiskit 2.3.1 with all its features
• Extensible: Easy to add new tools or backends

Installation

Prerequisites

• Python 3.11 or higher
• Qiskit 2.3.1
• A running MCP client (Claude Desktop, Cursor, etc.)

Install from PyPI

pip install mcp-qiskit[qiskit]

The [qiskit] extra installs the required Qiskit dependencies. Other extras available:

# Install with development dependencies

pip install mcp-qiskit[dev,test]

Install with MCP server dependencies

pip install mcp-qiskit[mcp]

Install from Source

git clone https://github.com/daedalus/mcp-qiskit.git

cd mcp-qiskit pip install -e ".[all]"

Quick Start

As a Python Library

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']}")

As an MCP Server

Claude Desktop

Add to your claude_desktop_config.json:

{

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

Cursor

Add to your Cursor settings under MCP Servers:

{

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

Other MCP Clients

# Run as stdio server

mcp-qiskit

Or use the Python module directly

python -m mcp_qiskit

MCP Tools Reference

Circuit Creation Tools

create_quantum_circuit_tool

Creates an empty quantum circuit with specified number of qubits and classical bits.

Parameters:

• num_qubits (int): Number of quantum bits
• num_classical_bits (int): Number of classical bits for measurements

Returns: Dictionary representing the circuit

Example:

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

Adds a quantum gate to a circuit. This tool maintains circuit state between calls.

Parameters:

• circuit (dict, optional): The circuit to modify. If None, creates a new 8-qubit circuit with 8 classical bits automatically.
• gate_name (str): Name of the gate (e.g., "h", "x", "cx", "rx")
• qubits (list[int]): List of qubit indices to apply the gate to. Can be a single qubit (e.g., [0]) or multiple qubits (e.g., [0, 1, 2, 3]). When multiple qubits are specified for a single-qubit gate, the gate is applied to each qubit.
• params (list[float], optional): Parameters for parameterized gates

Supported Gates:

• Single-qubit: h, x, y, z, s, t, sdg, tdg, i, id
• Parameterized: rx, ry, rz, u1, u2, u3, p
• Multi-qubit: cx, cy, cz, swap
• Multi-controlled: mcx, mct, mcp, ccx, toffoli, c3x, c3sx, c4x
• Specialized: rxx, ryy, rzz, ch, cswap, cu, crx, cry, crz

State Maintenance Pattern: Always pass the circuit returned by the previous call to maintain state:

# 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])

Apply Single-Quantum Gate to Multiple Qubits: When applying single-qubit gates (like h, x, y, z, etc.) to multiple qubits at once, use a list of qubit indices:

# 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

Adds multiple quantum gates to a circuit in a single call. This tool maintains circuit state between calls and reduces the number of tool calls needed.

Parameters:

• circuit (dict, optional): The circuit to modify. If None, creates a new 8-qubit circuit with 8 classical bits automatically.
• gates (list[dict]): List of gate specifications, each containing:
• gate (str): Name of the gate (e.g., "h", "x", "cx", "rx")
• qubits (list[int]): Qubit indices to apply the gate to
• params (list[float], optional): Parameters for parameterized gates

Example:

# 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

Adds measurement operations to qubits. This tool maintains circuit state between calls.

Parameters:

• circuit (dict, optional): The circuit to modify. If None, creates a new 8-qubit circuit with 8 classical bits automatically.
• qubits (list[int]): Qubit indices to measure
• clbits (list[int], optional): Classical bit indices to store results

Example:

# 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

Analysis Tools

get_circuit_depth_tool

Returns the depth (number of layers) of the circuit.

Parameters:

• circuit (dict): The circuit to analyze

Returns: Integer representing circuit depth

list_available_gates_tool

Lists all available quantum gates in Qiskit.

Returns: List of gate name strings

get_gate_definition_tool

Gets detailed information about a quantum gate.

Parameters:

• gate_name (str): Name of the gate

Returns: Dictionary with gate properties:

• name: Gate name
• num_qubits: Number of qubits the gate operates on
• num_parameters: Number of parameters (0 for fixed gates)
• params: List of parameter values

Visualization Tools

draw_circuit_tool

Renders a circuit in various formats.

Parameters:

• circuit (dict): The circuit to draw
• output_format (str): Output format - "ascii", "text", "mpl", "latex"

Returns: String representation of the circuit

Example Output (ASCII):

     ┌───┐

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

Backend Tools

list_backends_tool

Lists available quantum backends.

Parameters:

• filters (dict, optional): Filter criteria (e.g., {"status": "ONLINE"})

Returns: List of backend information dictionaries

get_backend_status_tool

Gets status information for a backend.

Parameters:

• backend_name (str): Name of the backend

Returns: Dictionary with:

• name: Backend name
• status: Status (ONLINE/OFFLINE)
• num_qubits: Number of qubits

get_backend_configuration_tool

Gets detailed configuration for a backend.

Parameters:

• backend_name (str): Name of the backend

Returns: Dictionary with:

• name: Backend name
• num_qubits: Number of qubits
• coupling_map: Qubit connectivity (if applicable)
• basis_gates: List of available basis gates
• max_shots: Maximum allowed shots

Execution Tools

run_circuit_tool

Executes a single quantum circuit.

Parameters:

• circuit (dict): Circuit to execute
• backend_name (str, optional): Backend name (default: "aer_simulator")
• shots (int, optional): Number of measurement shots (default: 1024)
• seed (int, optional): Random seed for reproducibility

Returns: Dictionary with:

• status: "COMPLETED" or error message
• backend: Backend used
• shots: Number of shots
• counts: Measurement outcome counts (if shots > 0)
• statevector: Statevector (if shots=None)
• time_taken: Execution time in seconds

Example:

result = run_circuit_tool(circuit, "aer_simulator", shots=1000, seed=42)

Returns: {"status": "COMPLETED", "counts": {"00": 512, "11": 488}, ...}

run_circuits_tool

Executes multiple circuits in a batch.

Parameters:

• circuits (list[dict]): List of circuits to execute
• backend_name (str, optional): Backend name
• shots (int, optional): Number of shots
• seed (int, optional): Random seed

Returns: List of result dictionaries

Example:

circuits = [circuit1, circuit2, circuit3]

results = run_circuits_tool(circuits, shots=100)

Returns list of 3 result dictionaries

transpile_circuit_tool

Transpiles a circuit for optimization or specific backend.

Parameters:

• circuit (dict): Circuit to transpile
• optimization_level (int, optional): 0-3 (default: 1)
• basis_gates (list[str], optional): Target basis gates

Returns: Transpiled circuit dictionary

Example:

transpiled = transpile_circuit_tool(circuit, optimization_level=2)

MCP Resources

resource://backends

Provides a list of available quantum backends. Updated dynamically based on available providers.

resource://gates

Provides a list of all available quantum gates in Qiskit.

Usage Examples

Create a Bell State

# 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}

Run Grover'