Qiskit IBM Runtime MCP Server

Qiskit IBM Runtime MCP Server

A comprehensive Model Context Protocol (MCP) server that provides AI assistants with access to IBM Quantum computing services through Qiskit IBM Runtime. This server enables quantum circuit creation, execution, and management directly from AI conversations.

Features

• Circuit Execution with Primitives: Run circuits using EstimatorV2 (expectation values) and SamplerV2 (measurement sampling) with built-in error mitigation
• Quantum Backend Management: List, inspect, and get calibration data for quantum backends
• Qubit Optimization: Find optimal qubit chains and subgraphs based on real-time calibration data
• Job Management: Monitor, cancel, and retrieve job results
• Account Management: Easy setup and configuration of IBM Quantum accounts

Prerequisites

• Python 3.10 or higher
• IBM Quantum account (free at quantum.cloud.ibm.com)
• IBM Quantum API token

Installation

Install from PyPI

The easiest way to install is via pip:

pip install qiskit-ibm-runtime-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

1. Get your IBM Quantum token (if you don't have saved credentials):

• Visit IBM Quantum
• Find your API key. From the dashboard, create your API key, then copy it to a secure location so you can use it for authentication. More information

1. Configure your credentials (choose one method):

Option A: Environment Variable (Recommended)

   # Copy the example environment file

cp .env.example .env

Edit .env and add your IBM Quantum API token

export QISKIT_IBM_TOKEN="your_token_here"

Optional: Set instance for faster startup (skips instance lookup)

export QISKIT_IBM_RUNTIME_MCP_INSTANCE="your-instance-crn"

Option B: Save Credentials Locally

   from qiskit_ibm_runtime import QiskitRuntimeService

Save your credentials (one-time setup)

QiskitRuntimeService.save_account( channel="ibm_quantum_platform", token="your_token_here", overwrite=True )

   This stores your credentials in `~/.qiskit/qiskit-ibm.json`

Option C: Pass Token Directly

   # Provide token when setting up the account

await setup_ibm_quantum_account_tool(token="your_token_here")

Credential Resolution Priority: The server looks for credentials in this order:

1. Explicit token passed to setup_ibm_quantum_account_tool()
2. QISKIT_IBM_TOKEN environment variable
3. Saved credentials in ~/.qiskit/qiskit-ibm.json

Instance Configuration (Optional): To speed up service initialization, you can specify your IBM Quantum instance:

• Set QISKIT_IBM_RUNTIME_MCP_INSTANCE environment variable with your instance CRN
• This skips the automatic instance lookup which can be slow
• Find your instance CRN in IBM Quantum Platform

Instance Priority:

• If you saved credentials with an instance (via save_account(instance="...")), the SDK uses it automatically
• QISKIT_IBM_RUNTIME_MCP_INSTANCE overrides any instance saved in credentials
• If neither is set, the SDK performs a slow lookup across all instances

Note: QISKIT_IBM_RUNTIME_MCP_INSTANCE is an MCP server-specific variable, not a standard Qiskit SDK environment variable.

Quick Start

Running the Server

uv run qiskit-ibm-runtime-mcp-server

The server will start and listen for MCP connections.

Basic Usage Examples

Async Usage (Library)

# 1. Setup IBM Quantum Account (optional if credentials already configured)

Will use saved credentials or environment variable if token not provided

await setup_ibm_quantum_account() # Uses saved credentials/env var

OR

await setup_ibm_quantum_account(token="your_token_here") # Explicit token

2. List Available Backends (no setup needed if credentials are saved)

backends = await list_backends() print(f"Available backends: {len(backends['backends'])}")

3. Get the least busy backend

backend = await least_busy_backend() print(f"Least busy backend: {backend}")

4. Get backend's properties

backend_props = await get_backend_properties("backend_name") print(f"Backend_name properties: {backend_props}")

5. List recent jobs

jobs = await list_my_jobs(10) print(f"Last 10 jobs: {jobs}")

6. Get job status

job_status = await get_job_status("job_id") print(f"Job status: {job_status}")

7. Get job results (when job is DONE)

results = await get_job_results("job_id") print(f"Counts: {results['counts']}")

8. Cancel job

cancelled_job = await cancel_job("job_id") print(f"Cancelled job: {cancelled_job}")

Sync Usage (Scripts, Jupyter)

For frameworks that don't support async operations, all async functions have a .sync attribute:

from qiskit_ibm_runtime_mcp_server.ibm_runtime import (

setup_ibm_quantum_account, list_backends, least_busy_backend, get_backend_properties, get_backend_calibration, get_coupling_map, find_optimal_qubit_chains, find_optimal_qv_qubits, run_estimator, run_sampler, list_my_jobs, get_job_status, get_job_results, cancel_job )

Optional: Setup account if not already configured

Will automatically use QISKIT_IBM_TOKEN env var or saved credentials

setup_ibm_quantum_account.sync() # No token needed if already configured

Use .sync for synchronous execution - no setup needed if credentials saved

backends = list_backends.sync() print(f"Available backends: {backends['total_backends']}")

Get least busy backend

backend = least_busy_backend.sync() print(f"Least busy: {backend['backend_name']}")

Find optimal qubit chains for linear experiments

chains = find_optimal_qubit_chains.sync(backend['backend_name'], chain_length=5) print(f"Best chain: {chains'chains'['qubits']}")

Find optimal qubits for Quantum Volume experiments

qv_qubits = find_optimal_qv_qubits.sync(backend['backend_name'], num_qubits=5) print(f"Best QV subgraph: {qv_qubits'subgraphs'['qubits']}")

Works in Jupyter notebooks (handles nested event loops automatically)

jobs = list_my_jobs.sync(limit=5) print(f"Recent jobs: {len(jobs['jobs'])}")

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()

async def main():

Configure MCP client

mcp_client = MultiServerMCPClient({ "qiskit-ibm-runtime": { "transport": "stdio", "command": "qiskit-ibm-runtime-mcp-server", "args": [], "env": { "QISKIT_IBM_TOKEN": os.getenv("QISKIT_IBM_TOKEN", ""), "QISKIT_IBM_RUNTIME_MCP_INSTANCE": os.getenv("QISKIT_IBM_RUNTIME_MCP_INSTANCE", ""), }, } })

Use persistent session for efficient tool calls

async with mcp_client.session("qiskit-ibm-runtime") 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("What QPUs are available and which one is least busy?") 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

These are the names MCP clients see in tools/list. Hosts can add a prefix to them (for example mcp__ __ ), so check how your client shows the name before you write an allowlist or a permission rule. The Python functions in qiskit_ibm_runtime_mcp_server.ibm_runtime (see Sync Usage) have the same names without the _tool suffix.

setup_ibm_quantum_account_tool(token: str = "", channel: str = "ibm_quantum_platform")

Configure IBM Quantum account with API token.

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.

list_backends_tool()

Get list of available quantum backends.

Returns: Array of backend information including:

• Name, status, queue length
• Number of qubits, coupling map
• Simulator vs. hardware designation

least_busy_backend_tool()

Get the current least busy IBM Quantum backend available.

Returns: The backend with the fewest number of pending jobs

get_backend_properties_tool(backend_name: str)

Get detailed properties of specific backend.

Returns: Complete backend configuration including:

• Hardware specifications
• Gate set and coupling map
• Current operational status
• Queue information

get_coupling_map_tool(backend_name: str)

Get the coupling map (qubit connectivity) for a backend with detailed analysis.

Supports both real backends (requires credentials) and fake backends (no credentials needed). Use fake_ prefix for offline testing (e.g., fake_sherbrooke, fake_brisbane).

Parameters:

• backend_name: Name of the backend (e.g., ibm_brisbane or fake_sherbrooke)

Returns: Connectivity information including:

• edges: List of [control, target] qubit connection pairs
• adjacency_list: Neighbor mapping for each qubit
• bidirectional: Whether all connections work in both directions
• num_qubits: Total qubit count

Use cases:

• Circuit optimization and qubit mapping
• SWAP gate minimization planning
• Offline testing with fake backends

get_backend_calibration_tool(backend_name: str, qubit_indices: list[int] | None = None)

Get calibration data for a backend including T1, T2 coherence times and error rates.

Parameters:

• backend_name: Name of the backend (e.g., ibm_brisbane)
• qubit_indices (optional): List of specific qubit indices. If not provided, returns data for the first 10 qubits.

Returns: Calibration data including:

• T1 and T2 coherence times (in microseconds)
• Qubit frequency (in GHz)
• Readout errors for each qubit
• Gate errors for common gates (x, sx, cx, etc.)
• faulty_qubits