qiskit-ibm-transpiler-mcp-server

MCP server for Qiskit transpiler. It supports AI routing, AI Clifford synthesis, AI Linear Function synthesis, AI Permutation synthesis, and AI Pauli Network synthesis using QASM 3.0 as the input/output tools format.

Features

• AI transpiler: Perform machine learning-based optimizations in both routing and synthesis passes
• QPY output: Returns base64-encoded QPY format for precision when chaining tools/servers
• Dual input format: Accepts both QASM 3.0 strings and base64-encoded QPY as input

Prerequisites

• python>=3.10 and <3.14
• qiskit-ibm-transpiler==0.15.0
• fastmcp>=2.12.4

Installation

Install from PyPI

The easiest way to install is via pip:

pip install qiskit-ibm-transpiler-mcp-server

Install from Source

This project recommends using uv for virtual environments and dependencies management. If you don't have uv installed, check out the instructions in https://docs.astral.sh/uv/getting-started/installation/

Setting up the Project with uv

1. Initialize or sync the project:
   bash

   # This will create a virtual environment and install dependencies
   uv sync
   

Quick Start

Running the Server

uv run qiskit-ibm-transpiler-mcp-server

The server will start and listen for MCP connections.

Sync Usage (Scripts, Jupyter)

For frameworks that don't support async operations:

from qiskit_ibm_transpiler_mcp_server.qta import (
    ai_routing,
    ai_clifford_synthesis
)
from qiskit_ibm_transpiler_mcp_server.utils import setup_ibm_quantum_account

from dotenv import load_dotenv

load_dotenv()

# 1. Load Quantum Circuit to be synthesized as QASM 3.0 string
qasm_string = "your_qasm_circuit_here"

# 2. Setup IBM Quantum Account (optional if credentials already configured)
# Will use saved credentials or environment variable if token not provided
setup_ibm_quantum_account.sync()

# Works in Jupyter notebooks
# 3. AI Clifford Synthesis

# 3.1 AI Routing [Optional]
routed_circuit = ai_routing.sync(circuit=qasm_string, backend_name="backend_name")
# Response contains QPY format (base64-encoded) for precision when chaining
routed_qpy_string = routed_circuit['circuit_qpy']
print(f"Routed circuit (QPY): {routed_qpy_string}")

# 3.2 AI Clifford Synthesis pass (use QPY for chaining)
clifford_synthesized_circuit = ai_clifford_synthesis.sync(
    circuit=routed_qpy_string,
    backend_name="backend_name",
    circuit_format="qpy"  # Specify QPY input format
)
print(f"Clifford synthesized circuit (QPY): {clifford_synthesized_circuit['circuit_qpy']}")

# 4. Convert QPY to human-readable QASM3 (optional)
from qiskit_mcp_server import qpy_to_qasm3
conversion = qpy_to_qasm3(clifford_synthesized_circuit['circuit_qpy'])
if conversion["status"] == "success":
    print(f"Human-readable circuit:\n{conversion['qasm3']}")

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 (QISKIT_IBM_TOKEN, OPENAI_API_KEY, etc.)
load_dotenv()

# Sample Clifford circuit
SAMPLE_CLIFFORD = """
OPENQASM 3.0;
include "stdgates.inc";
qubit[3] q;
h q[0];
cx q[0], q[1];
s q[2];
"""

async def main():
    # Configure MCP client
    mcp_client = MultiServerMCPClient({
        "qiskit-ibm-transpiler": {
            "transport": "stdio",
            "command": "qiskit-ibm-transpiler-mcp-server",
            "args": [],
            "env": {
                "QISKIT_IBM_TOKEN": os.getenv("QISKIT_IBM_TOKEN", ""),
            },
        }
    })

    # Use persistent session for efficient tool calls
    async with mcp_client.session("qiskit-ibm-transpiler") 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"Synthesize this Clifford circuit for ibm_fez: {SAMPLE_CLIFFORD}")
        print(response)

asyncio.run(main())

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

Other ways of testing and debugging the server

1. From a terminal, go into the cloned repo directory

2. Switch to the virtual environment

   sh

   source .venv/bin/activate
   

3. Run the MCP Inspector:

   sh

   npx @modelcontextprotocol/inspector uv run qiskit-ibm-transpiler-mcp-server
   

4. Open your browser to the URL shown in the console message e.g.,

   code

   MCP Inspector is up and running at http://localhost:6277
   

Note: to launch the MCP inspector you will need to have node and npm

API Reference

Tools

Setup IBM Account

Configure IBM Quantum account with API token.

setup_ibm_quantum_account_tool(token: Optional[str] = None, channel: str = "ibm_quantum_platform")

Parameters:

• token (optional): IBM Quantum API token. If not provided, the function will:
  1. Check for QISKIT_IBM_TOKEN environment variable
  2. Use saved credentials from ~/.qiskit/qiskit-ibm.json
• channel: Service channel (default: "ibm_quantum_platform")

Returns: Setup status and account information

Note: If you already have saved credentials or have set the QISKIT_IBM_TOKEN environment variable, you can call this function without parameters or skip it entirely and use other functions directly.

AI Routing

Route input quantum circuit. It inserts SWAP operations on a circuit to make two-qubits operations compatible with a given coupling map that restricts the pair of qubits on which operations can be applied. You may want to execute routing pass before any other AI transpiling synthesis pass.

ai_routing(
   circuit: str,
   backend_name: str,
   optimization_level: int = 1,
   layout_mode: str = "optimize",
   optimization_preferences: Literal[
      "n_cnots", "n_gates", "cnot_layers", "layers", "noise"
      ] | list[Literal["n_cnots", "n_gates", "cnot_layers", "layers", "noise"]] | None = None,
   local_mode: bool = True,
   coupling_map: list[list[int]] | None = None,
   circuit_format: str = "qasm3"
)

Parameters:

• circuit: quantum circuit as QASM 3.0 string or base64-encoded QPY
• backend_name: Qiskit Runtime Service backend name on which to map the input circuit synthesis
• optimization_level (optional): The potential optimization level to apply during the transpilation process. Valid values are [1,2,3], where 1 is the least optimization (and fastest), and 3 the most optimization (and most time-intensive)
• layout_mode (optional): Specifies how to handle the layout selection. It can assume the following values:
  • "keep": This respects the layout set by the previous transpiler passes. Typically used when the circuit must be run on specific qubits of the device. It often produces worse results because it has less room for optimization
  • "improve": It is useful when you have a good initial guess for the layout
  • "optimize": This is the default mode. It works best for general circuits where you might not have good layout guesses. This mode ignores previous layout selections
• optimization_preferences (optional): Indicates what you want to reduce through optimization: number of cnot gates (n_cnots), number of gates (n_gates), number of cnots layers (cnot_layers), number of layers (layers), and/or noise (noise)
• local_mode (optional): determines where the AIRouting pass runs. If False, AIRouting runs remotely through the Qiskit Transpiler Service. If True, the package tries to run the pass in your local environment with a fallback to cloud mode if the required dependencies are not found
• coupling_map (optional): List of qubit pairs representing the backend topology. If provided, overrides the backend's coupling map. Useful for targeting a specific subset of qubits
• circuit_format (optional): Format of the input circuit ("qasm3" or "qpy"). Defaults to "qasm3"

Returns: Dictionary with:

• status: "success" or "error"
• circuit_qpy: Base64-encoded QPY format
• original_circuit: Metrics for the input circuit (num_qubits, depth, size, two_qubit_gates)
• optimized_circuit: Metrics for the optimized circuit (num_qubits, depth, size, two_qubit_gates)
• improvements: Calculated improvements (depth_reduction, two_qubit_gate_reduction)

Note: Currently, only the local mode execution is available

Hybrid AI Transpile

Transpile a quantum circuit using a hybrid pass manager that combines Qiskit's heuristic optimization with AI-powered transpiler passes. This provides end-to-end transpilation in a single unified pipeline.

hybrid_ai_transpile(
   circuit: str,
   backend_name: str,
   ai_optimization_level: int = 3,
   optimization_level: int = 3,
   ai_layout_mode: str = "optimize",
   initial_layout: list[int] | None = None,
   coupling_map: list[list[int]] | None = None,
   circuit_format: str = "qasm3"
)

Parameters:

• circuit: quantum circuit as QASM 3.0 string or base64-encoded QPY
• backend_name: Target IBM Quantum backend (e.g., 'ibm_boston', 'ibm_fez')
• ai_optimization_level (optional): Optimization level (1-3) for AI components. Higher values yield better results but require more computational resources
• optimization_level (optional): Optimization level (1-3) for heuristic components in the PassManager
• ai_layout_mode (optional): Specifies how the AI routing component handles layout selection:
  • "keep": Respects the layout set by previous transpiler passes
  • "improve": Uses prior layouts as starting points for optimization
  • "optimize": Default; ignores previous layout selections for general circuits. Note: If initial_layout is provided with 'optimize', it automatically converts to 'improve' to leverage the user-provided layout
• initial_layout (optional): List of physical qubit indices specifying where to place virtual qubits. For example, [0, 1, 5, 6, 7] maps virtual qubit 0 to physical qubit 0, virtual qubit 1 to physical qubit 1, etc.
• coupling_map (optional): List of qubit pairs representing the backend topology. If provided, overrides the backend's coupling map. Useful for targeting a specific subset of qubits
• circuit_format (optional): Format of the input circuit ("qasm3" or "qpy"). Defaults to "qasm3"

Returns: Dictionary with:

• status: "success" or "error"
• circuit_qpy: Base64-encoded QPY format
• original_circuit: Metrics for the input circuit (num_qubits, depth, size, two_qubit_gates)
• optimized_circuit: Metrics for the optimized circuit (num_qubits, depth, size, two_qubit_gates)
• improvements: Calculated improvements (depth_reduction, two_qubit_gate_reduction)

AI Clifford synthesis

Synthesis for Clifford circuits (blocks of H, S, and CX gates). Currently, up to nine qubit blocks.

ai_clifford_synthesis(
   circuit: str,
   backend_name: str,
   replace_only_if_better: bool = True,
   local_mode: bool = True,
   circuit_format: str = "qasm3"
)

Parameters:

• circuit: quantum circuit as QASM 3.0 string or base64-encoded QPY
• backend_name: Qiskit Runtime Service backend name on which to map the input circuit synthesis
• replace_only_if_better (optional): By default, the synthesis will replace the original sub-circuit only if the synthesized sub-circuit improves the original (currently only checking CNOT count), but this can be forced to always replace the circuit by setting replace_only_if_better=False
• local_mode (optional): determines where the AI Clifford synthesis runs. If False, AI Clifford synthesis runs remotely through the Qiskit Transpiler Service. If True, the package tries to run the pass in your local environment with a fallback to cloud mode if the required dependencies are not found
• circuit_format (optional): Format of the input circuit ("qasm3" or "qpy"). Defaults to "qasm3"

Returns: Dictionary with:

• status: "success" or "error"
• circuit_qpy: Base64-encoded QPY format
• original_circuit: Metrics for the input circuit (num_qubits, depth, size, two_qubit_gates)
• optimized_circuit: Metrics for the optimized circuit (num_qubits, depth, size, two_qubit_gates)
• improvements: Calculated improvements (depth_reduction, two_qubit_gate_reduction)

Note: Currently, only the local mode execution is available

AI Linear Function synthesis

Synthesis for Linear Function circuits (blocks of CX and SWAP gates). Currently, up to nine qubit blocks.

ai_linear_function_synthesis(
   circuit: str,
   backend_name: str,
   replace_only_if_better: bool = True,
   local_mode: bool = True,
   circuit_format: str = "qasm3"
)

Parameters:

• circuit: quantum circuit as QASM 3.0 string or base64-encoded QPY
• backend_name: Qiskit Runtime Service backend name on which to map the input circuit synthesis
• replace_only_if_better (optional): By default, the synthesis will replace the original sub-circuit only if the synthesized sub-circuit improves the original (currently only checking CNOT count), but this can be forced to always replace the circuit by setting replace_only_if_better=False
• local_mode (optional): determines where the Linear Function synthesis pass runs. If False, Linear Function synthesis runs remotely through the Qiskit Transpiler Service. If True, the package tries to run the pass in your local environment with a fallback to cloud mode if the required dependencies are not found
• circuit_format (optional): Format of the input circuit ("qasm3" or "qpy"). Defaults to "qasm3"

Returns: Dictionary with:

• status: "success" or "error"
• circuit_qpy: Base64-encoded QPY format
• original_circuit: Metrics for the input circuit (num_qubits, depth, size, two_qubit_gates)
• optimized_circuit: Metrics for the optimized circuit (num_qubits, depth, size, two_qubit_gates)
• improvements: Calculated improvements (depth_reduction, two_qubit_gate_reduction)

Note: Currently, only the local mode execution is available

AI Permutation synthesis

Synthesis for Permutation circuits (blocks of SWAP gates). Currently available for 65, 33, and 27 qubit blocks.

ai_permutation_synthesis(
   circuit: str,
   backend_name: str,
   replace_only_if_better: bool = True,
   local_mode: bool = True,
   circuit_format: str = "qasm3"
)

Parameters:

• circuit: quantum circuit as QASM 3.0 string or base64-encoded QPY
• backend_name: Qiskit Runtime Service backend name on which to map the input circuit synthesis
• replace_only_if_better (optional): By default, the synthesis will replace the original sub-circuit only if the synthesized sub-circuit improves the original (currently only checking CNOT count), but this can be forced to always replace the circuit by setting replace_only_if_better=False
• local_mode (optional): determines where the AI Permutation synthesis pass runs. If False, AI Permutation synthesis runs remotely through the Qiskit Transpiler Service. If True, the package tries to run the pass in your local environment with a fallback to cloud mode if the required dependencies are not found
• circuit_format (optional): Format of the input circuit ("qasm3" or "qpy"). Defaults to "qasm3"

Returns: Dictionary with:

• status: "success" or "error"
• circuit_qpy: Base64-encoded QPY format
• original_circuit: Metrics for the input circuit (num_qubits, depth, size, two_qubit_gates)
• optimized_circuit: Metrics for the optimized circuit (num_qubits, depth, size, two_qubit_gates)
• improvements: Calculated improvements (depth_reduction, two_qubit_gate_reduction)

Note: Currently, only the local mode execution is available

AI Pauli Network synthesis

Synthesis for Pauli Network circuits (blocks of H, S, SX, CX, RX, RY and RZ gates). Currently, up to six qubit blocks.

ai_pauli_network_synthesis(
   circuit: str,
   backend_name: str,
   replace_only_if_better: bool = True,
   local_mode: bool = True,
   circuit_format: str = "qasm3"
)

Parameters:

• circuit: quantum circuit as QASM 3.0 string or base64-encoded QPY
• backend_name: Qiskit Runtime Service backend name on which to map the input circuit synthesis
• replace_only_if_better (optional): By default, the synthesis will replace the original sub-circuit only if the synthesized sub-circuit improves the original (currently only checking CNOT count), but this can be forced to always replace the circuit by setting replace_only_if_better=False
• local_mode (optional): determines where the AI Pauli Network synthesis pass runs. If False, AI Pauli Network synthesis runs remotely through the Qiskit Transpiler Service. If True, the package tries to run the pass in your local environment with a fallback to cloud mode if the required dependencies are not found
• circuit_format (optional): Format of the input circuit ("qasm3" or "qpy"). Defaults to "qasm3"

Returns: Dictionary with:

• status: "success" or "error"
• circuit_qpy: Base64-encoded QPY format
• original_circuit: Metrics for the input circuit (num_qubits, depth, size, two_qubit_gates)
• optimized_circuit: Metrics for the optimized circuit (num_qubits, depth, size, two_qubit_gates)
• improvements: Calculated improvements (depth_reduction, two_qubit_gate_reduction)

Note: Currently, only the local mode execution is available

Testing

This project includes comprehensive unit and integration tests.

Running Tests

Quick test run:

./run_tests.sh

Manual test commands:

# Install test dependencies
uv sync --group dev --group test

# Run all tests
uv run pytest

# Run only unit tests
uv run pytest -m "not integration"

# Run only integration tests
uv run pytest -m "integration"

# Run tests with coverage
uv run pytest --cov=src --cov-report=html

# Run specific test file
uv run pytest tests/test_server.py -v

Test Structure

• tests/integration/test_qta.py - Integration tests for async server functions
• tests/integration/test_sync.py - Integration tests for sync server functions
• tests/integration/test_mcp_server.py - Generic integration tests
• tests/unit/test_qta.py - Unit tests for async server functions
• tests/unit/test_sync.py - Unit tests for sync server functions
• tests/unit/test_utils.py - Unit tests for utils functions
• tests/unit/test_qiskit_runtime_service_provider.py - Unit tests for QiskitRuntimeServiceProvider Singleton
• tests/conftest.py - Test fixtures and configuration
• tests/utils/helpers.py - Helper functions to compute 2-qubits count and depth improvement for integration tests
• tests/qasm/ - Three QASM 3.0 test cases in /qasm folder (2 valid, 1 malformed)

Test Coverage

The test suite covers:

• ✅ Service initialization and account setup
• ✅ AI synthesis passes (mocked and real)
• ✅ Error handling and validation
• ✅ Integration scenarios (mocked and real)
• ✅ Tool handlers

Areas for improvement

• Integrate Collections for complete AI synthesis pass