https://github.com/daedalus/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.
https://github.com/daedalus/mcp-qiskit
mcp qiskit quantum-computing
Last synced: 2 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/daedalus/mcp-qiskit
- Owner: daedalus
- License: mit
- Created: 2026-04-06T00:09:59.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-06T01:53:25.000Z (2 months ago)
- Last Synced: 2026-04-06T02:28:32.597Z (2 months ago)
- Topics: mcp, qiskit, quantum-computing
- Language: Python
- Homepage:
- Size: 28.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 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.
[](https://pypi.org/project/mcp-qiskit/)
[](https://pypi.org/project/mcp-qiskit/)
[](https://github.com/astral-sh/ruff)
[](https://github.com/daedalus/mcp-qiskit/actions)
mcp-name: io.github.daedalus/mcp-qiskit
## Overview
This project provides a Model Context Protocol (MCP) server that exposes [Qiskit](https://qiskit.com/) 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
```bash
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
```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']}")
```
### As an MCP Server
#### Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"mcp-qiskit": {
"command": "mcp-qiskit",
"env": {}
}
}
}
```
#### Cursor
Add to your Cursor settings under MCP Servers:
```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):**
```
┌───┐
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
```python
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
```
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:
1. **Aer Simulator** (default) - Runs locally, no API key required
2. **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**
```bash
export IBM_QUANTUM_TOKEN="your_api_token_here"
```
Or in your Python code:
```python
import os
os.environ["IBM_QUANTUM_TOKEN"] = "your_api_token_here"
```
**Option 2: Save Credentials via Qiskit**
```python
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:**
1. Create an account at [IBM Quantum](https://quantum.ibm.com/)
2. Go to Account > My Tokens
3. Copy your API token
**Environment Variable for MCP Server:**
When running as an MCP server, set the environment variable before starting:
```bash
export IBM_QUANTUM_TOKEN="your_token"
mcp-qiskit
```
Or in your MCP client configuration:
```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:
```bash
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](LICENSE) file.
## Contributing
Contributions are welcome! Please open an issue or submit a PR on GitHub.
## Related Projects
- [Qiskit](https://qiskit.com/) - Quantum computing SDK
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP framework
- [Model Context Protocol](https://modelcontextprotocol.io/) - Protocol specification