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.