Qiskit IBM Transpiler MCP Server

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:

   # 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

1. Run the MCP Inspector: sh npx @modelcontextprotocol/inspector uv run qiskit-ibm-transpiler-mcp-server

1. Open your browser to the URL shown in the console message e.g., 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 = T