mcp-qiskit
Advanced tools
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
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:
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]
git clone https://github.com/daedalus/mcp-qiskit.git
cd mcp-qiskit
pip install -e ".[all]"
from mcp_qiskit import create_quantum_circuit, add_gate, 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])
# 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']}")
Add to your claude_desktop_config.json:
{
"mcpServers": {
"mcp-qiskit": {
"command": "mcp-qiskit",
"env": {}
}
}
}
Add to your Cursor settings under MCP Servers:
{
"mcpServers": {
"mcp-qiskit": {
"command": "mcp-qiskit",
"args": []
}
}
}
# Run as stdio server
mcp-qiskit
# Or use the Python module directly
python -m mcp_qiskit
Creates an empty quantum circuit with specified number of qubits and classical bits.
Parameters:
num_qubits (int): Number of quantum bitsnum_classical_bits (int): Number of classical bits for measurementsReturns: 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"}
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 gatesSupported Gates:
h, x, y, z, s, t, sdg, tdg, i, idrx, ry, rz, u1, u2, u3, pcx, cy, cz, swapmcx, mct, mcp, ccx, toffoli, c3x, c3sx, c4xrxx, ryy, rzz, ch, cswap, cu, crx, cry, crzState 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])
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 measureclbits (list[int], optional): Classical bit indices to store resultsExample:
# 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
Returns the depth (number of layers) of the circuit.
Parameters:
circuit (dict): The circuit to analyzeReturns: Integer representing circuit depth
Lists all available quantum gates in Qiskit.
Returns: List of gate name strings
Gets detailed information about a quantum gate.
Parameters:
gate_name (str): Name of the gateReturns: Dictionary with gate properties:
name: Gate namenum_qubits: Number of qubits the gate operates onnum_parameters: Number of parameters (0 for fixed gates)params: List of parameter valuesRenders a circuit in various formats.
Parameters:
circuit (dict): The circuit to drawoutput_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
Lists available quantum backends.
Parameters:
filters (dict, optional): Filter criteria (e.g., {"status": "ONLINE"})Returns: List of backend information dictionaries
Gets status information for a backend.
Parameters:
backend_name (str): Name of the backendReturns: Dictionary with:
name: Backend namestatus: Status (ONLINE/OFFLINE)num_qubits: Number of qubitsGets detailed configuration for a backend.
Parameters:
backend_name (str): Name of the backendReturns: Dictionary with:
name: Backend namenum_qubits: Number of qubitscoupling_map: Qubit connectivity (if applicable)basis_gates: List of available basis gatesmax_shots: Maximum allowed shotsExecutes a single quantum circuit.
Parameters:
circuit (dict): Circuit to executebackend_name (str, optional): Backend name (default: "aer_simulator")shots (int, optional): Number of measurement shots (default: 1024)seed (int, optional): Random seed for reproducibilityReturns: Dictionary with:
status: "COMPLETED" or error messagebackend: Backend usedshots: Number of shotscounts: Measurement outcome counts (if shots > 0)statevector: Statevector (if shots=None)time_taken: Execution time in secondsExample:
result = run_circuit_tool(circuit, "aer_simulator", shots=1000, seed=42)
# Returns: {"status": "COMPLETED", "counts": {"00": 512, "11": 488}, ...}
Executes multiple circuits in a batch.
Parameters:
circuits (list[dict]): List of circuits to executebackend_name (str, optional): Backend nameshots (int, optional): Number of shotsseed (int, optional): Random seedReturns: List of result dictionaries
Example:
circuits = [circuit1, circuit2, circuit3]
results = run_circuits_tool(circuits, shots=100)
# Returns list of 3 result dictionaries
Transpiles a circuit for optimization or specific backend.
Parameters:
circuit (dict): Circuit to transpileoptimization_level (int, optional): 0-3 (default: 1)basis_gates (list[str], optional): Target basis gatesReturns: Transpiled circuit dictionary
Example:
transpiled = transpile_circuit_tool(circuit, optimization_level=2)
Provides a list of available quantum backends. Updated dynamically based on available providers.
Provides a list of all available quantum gates in 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']}")
See examples/shor_example.py for a complete implementation with factor extraction.
Build Shor's algorithm circuit to factor N=15 using the MCP Qiskit server tools:
# 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
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 install
This package supports two types of backends:
To use IBM Quantum backends, you need to provide your API token:
Option 1: Environment Variable
export IBM_QUANTUM_TOKEN="your_api_token_here"
Or in your Python code:
import os
os.environ["IBM_QUANTUM_TOKEN"] = "your_api_token_here"
Option 2: Save Credentials via 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
Getting an IBM Quantum Token:
Environment Variable for MCP Server:
When running as an MCP server, set the environment variable before starting:
export IBM_QUANTUM_TOKEN="your_token"
mcp-qiskit
Or in your MCP client configuration:
{
"mcpServers": {
"mcp-qiskit": {
"command": "mcp-qiskit",
"env": {
"IBM_QUANTUM_TOKEN": "your_token_here"
}
}
}
}
If you get "Backend not found", ensure the backend name is correct:
# List available backends
backends = list_backends()
print([b["name"] for b in backends])
Make sure Qiskit is properly installed:
pip install qiskit==2.3.1 qiskit-aer
Verify the server is running:
mcp-qiskit --help
MIT License - see LICENSE file.
Contributions are welcome! Please open an issue or submit a PR on GitHub.
FAQs
MCP server exposing Qiskit 2.3.1 quantum computing functionality
The pypi package mcp-qiskit receives a total of 30 weekly downloads. As such, mcp-qiskit popularity was classified as not popular.
We found that mcp-qiskit demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A misconfiguration gave three Anthropic models internet access, and one, believing it was in a simulation, shipped a credential-stealing package to PyPI.
Security News
/Company News
Socket has joined the new Composer and Packagist sponsorship program as a launch sponsor, supporting the team that keeps PHP's package ecosystem secure.
Research
/Security News
Benign-looking npm packages split malicious functionality across a dependency chain that deploys a cross-platform RAT targeting Alibaba developers.