Qiskit MCP Server

Qiskit MCP Server

A Model Context Protocol (MCP) server that provides quantum circuit transpilation capabilities using Qiskit's pass managers. This server enables AI assistants to optimize quantum circuits for various hardware targets.

Features

• Circuit Transpilation: Transpile quantum circuits with configurable optimization levels (0-3)
• Preset Basis Gates: Support for IBM Eagle, IBM Heron, ion trap, and other basis gate sets
• Topology Support: Built-in support for linear, ring, grid, and custom coupling maps
• Circuit Analysis: Analyze circuit complexity without transpilation
• Optimization Comparison: Compare results across all optimization levels
• Dual API: Supports both async (MCP) and sync (Jupyter, scripts) usage

Prerequisites

• Python 3.10 or higher
• uv package manager (recommended) or pip

Installation

From PyPI (when published)

pip install qiskit-mcp-server

From Source

# Clone the repository

git clone https://github.com/Qiskit/mcp-servers.git cd mcp-servers/qiskit-mcp-server

Install with uv

uv sync

Or with pip

pip install -e .

Quick Start

Running the MCP Server

# With uv

uv run qiskit-mcp-server

Or directly

qiskit-mcp-server

Claude Desktop Configuration

Add to your Claude Desktop configuration (claude_desktop_config.json):

{

"mcpServers": { "qiskit": { "command": "uv", "args": [ "--directory", "/path/to/qiskit-mcp-servers/qiskit-mcp-server", "run", "qiskit-mcp-server" ] } } }

Usage Examples

Async Usage (MCP Server / FastAPI)

from qiskit_mcp_server.transpiler import transpile_circuit

Simple Bell state circuit (QASM2 - automatically detected)

qasm = """OPENQASM 2.0; include "qelib1.inc"; qreg q[2]; creg c[2]; h q[0]; cx q[0], q[1]; measure q -> c; """

Transpile with default settings (optimization level 2, QASM3 format)

result = await transpile_circuit(qasm)

Transpile for IBM Heron processor

result = await transpile_circuit( qasm, optimization_level=3, basis_gates="ibm_heron", coupling_map="linear" )

Using QPY Format

from qiskit import QuantumCircuit

from qiskit_mcp_server import dump_qpy_circuit from qiskit_mcp_server.transpiler import transpile_circuit

Create a circuit programmatically

qc = QuantumCircuit(2, 2) qc.h(0) qc.cx(0, 1) qc.measure([0, 1], [0, 1])

Convert to QPY (preserves exact parameters and metadata)

qpy_circuit = dump_qpy_circuit(qc)

Transpile using QPY format

result = await transpile_circuit(qpy_circuit, circuit_format="qpy")

Result includes transpiled circuit in QPY format (for chaining)

transpiled_qpy = result"transpiled_circuit"

Chain to another operation using QPY

result2 = await transpile_circuit(transpiled_qpy, circuit_format="qpy", optimization_level=3)

Sync Usage (Scripts, Jupyter)

from qiskit_mcp_server.transpiler import transpile_circuit, analyze_circuit

All async functions have a .sync attribute

result = transpile_circuit.sync(qasm, optimization_level=2)

Analyze circuit without transpiling

analysis = analyze_circuit.sync(qasm) print(f"Circuit depth: {analysis'circuit_info'}") print(f"Two-qubit gates: {analysis'gate_categories'}")

Compare Optimization Levels

from qiskit_mcp_server.transpiler import compare_optimization_levels

Compare all optimization levels (0-3) for your circuit

comparison = compare_optimization_levels.sync(qasm)

for level in range(4): result = comparison'optimization_results' print(f"Level {level}: depth={result['depth']}, size={result['size']}")

LangChain Integration Example:

Note: To run LangChain examples you will need to install the dependencies:

`bash

pip install langchain langchain-mcp-adapters langchain-openai python-dotenv

`

import asyncio

import os from langchain.agents import create_agent from langchain_mcp_adapters.client import MultiServerMCPClient from langchain_mcp_adapters.tools import load_mcp_tools from langchain_openai import ChatOpenAI from dotenv import load_dotenv

Load environment variables (OPENAI_API_KEY, etc.)

load_dotenv()

Sample Bell state circuit

SAMPLE_BELL = """ OPENQASM 3.0; include "stdgates.inc"; qubit[2] q; h q[0]; cx q[0], q[1]; """

async def main():

Configure MCP client

mcp_client = MultiServerMCPClient({ "qiskit": { "transport": "stdio", "command": "qiskit-mcp-server", "args": [], "env": {}, } })

Use persistent session for efficient tool calls

async with mcp_client.session("qiskit") as session: tools = await load_mcp_tools(session)

Create agent with LLM

llm = ChatOpenAI(model="gpt-5.2", temperature=0) agent = create_agent(llm, tools)

Run a query

response = await agent.ainvoke(f"Transpile this circuit for IBM Heron: {SAMPLE_BELL}") print(response)

asyncio.run(main())

For more LLM providers (Anthropic, Google, Ollama, Watsonx) and detailed examples including Jupyter notebooks, see the examples/ directory.

API Reference

Tools

Resources

Core Functions

transpile_circuit(circuit, optimization_level=2, basis_gates=None, coupling_map=None, initial_layout=None, seed_transpiler=None, circuit_format="qasm3")

Transpile a quantum circuit using Qiskit's preset pass managers.

Parameters:

• circuit: Quantum circuit as QASM3 string, base64-encoded QPY, or QASM2 string (max 100 qubits, 10,000 gates)
• optimization_level: 0-3 (default: 2)
• 0: No optimization, only basis gate decomposition (fastest)
• 1: Light optimization with default layout
• 2: Medium optimization with noise-aware layout (recommended)
• 3: Heavy optimization for best results (can be slow for large circuits)
• basis_gates: List of gate names or preset ("ibm_default", "ibm_heron", etc.)
• coupling_map: List of edges or topology name ("linear", "ring", "grid", "full")
• initial_layout: List of physical qubit indices (length must match circuit qubits)
• seed_transpiler: Random seed for reproducibility
• circuit_format: Format of the input circuit ("qasm3" or "qpy"). Defaults to "qasm3". When "qasm3" is specified, QASM2 is also accepted as a fallback.

Returns: Dictionary with original/transpiled circuit info and optimization metrics

Note: Level 3 optimization can be very slow for circuits with >20 qubits or >500 gates. Use level 2 for faster results with good quality.

analyze_circuit(circuit, circuit_format="qasm3")

Analyze circuit structure and complexity.

Returns: Dictionary with gate counts, depth, and categorization (single/two/multi-qubit gates)

compare_optimization_levels(circuit, circuit_format="qasm3")

Compare transpilation results across all optimization levels.

Returns: Dictionary comparing depth, size, and gates for levels 0-3

Circuit Format Support

The server supports two circuit formats for input:

QPY output: All tools return circuits in QPY format (base64-encoded) for precision when chaining tools/servers.

When to use each format:

• QASM3 (input): Best for human-readable circuits and initial input
• QPY (input/output): Best for preserving exact numerical parameters when chaining tools/servers

Converting QPY to Human-Readable QASM3

To view a QPY circuit output in human-readable format, use the qpy_to_qasm3 utility:

from qiskit_mcp_server import qpy_to_qasm3

from qiskit_mcp_server.transpiler import transpile_circuit

Transpile a circuit (returns QPY format)

result = transpile_circuit.sync(qasm_circuit, optimization_level=2) qpy_output = result"transpiled_circuit"

Convert to human-readable QASM3

conversion = qpy_to_qasm3(qpy_output) if conversion["status"] == "success": print(conversion["qasm3"])

Converting QASM3 to QPY

To convert a QASM circuit to QPY format (for full fidelity when chaining tools), use qasm3_to_qpy:

from qiskit_mcp_server import qasm3_to_qpy

qasm_circuit = ''' OPENQASM 3.0; include "stdgates.inc"; qubit[2] q; h q[0]; cx q[0], q[1]; '''

Convert to QPY format

result = qasm3_to_qpy(qasm_circuit) if result["status"] == "success": qpy_string = result["circuit_qpy"]

Use qpy_string with tools that accept QPY input

Available Basis Gate Sets

You can also provide a custom list of gate names for other hardware targets.

Available Topologies

Limits and Performance

Circuit Size Limits

To ensure reliable performance, the server enforces the following limits:

Circuits exceeding these limits will return an error with a descriptive message.

You can override these limits via environment variables:

# Allow up to 200 qubits and 50,000 gates

export QISKIT_MCP_MAX_QUBITS=200 export QISKIT_MCP_MAX_GATES=50000

Performance Recommendations

Tips:

• Use level 2 for most use cases (best balance of quality and speed)
• Use level 3 only when circuit quality is critical AND circuit is small (<20 qubits, <500 gates)
• Use level 0 or 1 for rapid prototyping and development
• The `compare_optimizatio