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

Terminal

pip install mcp-qiskit[qiskit]

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

bash

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

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

Install from Source

bash

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

Quick Start

As a Python Library

server.ts

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:

config.json

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

Cursor

Add to your Cursor settings under MCP Servers:

config.json

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

Other MCP Clients

bash

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

python

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:

python

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

python

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

python

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

python

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

Code

     ┌───┐
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:

python

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:

python

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:

python

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

python

# 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's Algorithm

python

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)

Draw and Analyze Circuit

python

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)

Run Shor's Algorithm

server.ts

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

See examples/shor_example.py for a complete implementation with factor extraction.

Shor's Algorithm with MCP Qiskit Tools

Build Shor's algorithm circuit to factor N=15 using the MCP Qiskit server tools:

python

# 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

Architecture

Code

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

Module Responsibilities

_circuit.py: Quantum circuit creation, gates, measurements, visualization
_backend.py: Backend discovery, status, configuration
_execution.py: Circuit execution, transpilation
_mcp.py: FastMCP server definition, tool registration

Requirements

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

Development

Setup

bash

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

Running Tests

bash

pytest -v

Code Quality

bash

# Format code
ruff format src/ tests/

# Lint
ruff check src/ tests/

# Type check
mypy src/

Pre-commit Hooks

bash

pre-commit install

Troubleshooting

API Keys and Credentials

This package supports two types of backends:

Aer Simulator (default) - Runs locally, no API key required
IBM Quantum - Requires an IBM Quantum API token

Using IBM Quantum Backends

To use IBM Quantum backends, you need to provide your API token:

Option 1: Environment Variable

server.ts

export IBM_QUANTUM_TOKEN="your_api_token_here"

Or in your Python code:

server.ts

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

Option 2: Save Credentials via Qiskit

server.ts

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

Getting an IBM Quantum Token:

Create an account at IBM Quantum
Go to Account > My Tokens
Copy your API token

Environment Variable for MCP Server:

When running as an MCP server, set the environment variable before starting:

server.ts

export IBM_QUANTUM_TOKEN="your_token"
mcp-qiskit

Or in your MCP client configuration:

config.json

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

Backend Not Found

If you get "Backend not found", ensure the backend name is correct:

python

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

Import Errors

Make sure Qiskit is properly installed:

Terminal

pip install qiskit==2.3.1 qiskit-aer

MCP Connection Issues

Verify the server is running:

bash

mcp-qiskit --help

License

MIT License - see LICENSE file.

Contributing

Contributions are welcome! Please open an issue or submit a PR on GitHub.

Related Projects

Qiskit - Quantum computing SDK
FastMCP - MCP framework
Model Context Protocol - Protocol specification