qiskit-mcp-servers 0.9.0

Model Context Protocol servers for IBM Quantum services and Qiskit

Qiskit MCP Servers

A collection of Model Context Protocol (MCP) servers that provide AI assistants, LLMs, and agents with seamless access to IBM Quantum services and Qiskit libraries for quantum computing development and research.

🌟 What is This?

This repository contains production-ready MCP servers that enable AI systems to interact with quantum computing resources through Qiskit. Instead of manually configuring quantum backends, writing boilerplate code, or managing IBM Quantum accounts, AI assistants can now:

• 🤖 Generate intelligent quantum code with context-aware suggestions
• 🔌 Connect to real quantum hardware automatically
• 📊 Analyze quantum backends and find optimal resources
• 🚀 Execute quantum circuits and monitor job status
• 💡 Provide quantum computing assistance with expert knowledge

🛠️ Available Servers

🔬 Qiskit MCP Server

Core Qiskit quantum computing capabilities

Provides quantum circuit creation, manipulation, transpilation, and serialization utilities (QASM3, QPY) for local quantum development using Qiskit

📁 Directory: ./qiskit-mcp-server/

---

🧠 Qiskit Code Assistant MCP Server

Intelligent quantum code completion and assistance

Provides access to IBM's Qiskit Code Assistant for AI-assisted quantum programming

📁 Directory: ./qiskit-code-assistant-mcp-server/

---

⚙️ Qiskit IBM Runtime MCP Server

Complete access to IBM Quantum cloud services

Comprehensive interface to IBM Quantum hardware via Qiskit IBM Runtime

📁 Directory: ./qiskit-ibm-runtime-mcp-server/

---

🚀 Qiskit IBM Transpiler MCP Server

AI-powered circuit transpilation

Access to the qiskit-ibm-transpiler library for AI-optimized circuit routing and optimization.

📁 Directory: ./qiskit-ibm-transpiler-mcp-server/

---

📚 Qiskit Documentation MCP Server

Qiskit documentation retrieval and search

Query and retrieve Qiskit documentation, guides, and API references. No authentication required.

📁 Directory: ./qiskit-docs-mcp-server/

---

🏋️ Community Servers

🏋️ Qiskit Gym MCP Server

Reinforcement learning for quantum circuit synthesis

Uses qiskit-gym to train RL models for optimal quantum circuit synthesis, including permutation routing, linear function synthesis, and Clifford circuits.

📁 Directory: ./qiskit-gym-mcp-server/

📚 Examples

Each MCP server includes example code demonstrating how to build AI agents using LangChain:

Server	Examples
Qiskit MCP Server	qiskit-mcp-server/examples/
Qiskit Code Assistant MCP Server	qiskit-code-assistant-mcp-server/examples/
Qiskit IBM Runtime MCP Server	qiskit-ibm-runtime-mcp-server/examples/
Qiskit IBM Transpiler MCP Server	qiskit-ibm-transpiler-mcp-server/examples/
Qiskit Documentation MCP Server	qiskit-docs-mcp-server/examples/
Qiskit Gym MCP Server (Community)	qiskit-gym-mcp-server/examples/

Each examples directory contains:

• Jupyter Notebook (langchain_agent.ipynb) - Interactive tutorial with step-by-step examples
• Python Script (langchain_agent.py) - Command-line agent with multiple LLM provider support

Advanced: Quantum Volume Finder

The examples/ directory contains a multi-agent system that combines multiple MCP servers to find the highest achievable Quantum Volume for IBM Quantum backends through actual hardware execution. It demonstrates multi-server orchestration, local tool wrappers to keep large data out of the LLM context, and both single-circuit and full statistical protocol modes. See the examples README for details.

🚀 Quick Start

Prerequisites

• Python 3.10+ (3.11+ recommended)
• uv package manager (fastest Python package manager)
• IBM Quantum account and API token
• Qiskit Code Assistant access (for code assistant server)

Installation

Install from PyPI

# Install all MCP servers (core + community)
pip install qiskit-mcp-servers[all]

# Install just the core servers (default)
pip install qiskit-mcp-servers

# Install individual servers
pip install qiskit-mcp-servers[qiskit]          # Qiskit server only
pip install qiskit-mcp-servers[code-assistant]  # Code Assistant server only
pip install qiskit-mcp-servers[runtime]         # IBM Runtime server only
pip install qiskit-mcp-servers[transpiler]      # IBM Transpiler server only
pip install qiskit-mcp-servers[docs]            # Documentation server only
pip install qiskit-mcp-servers[gym]             # Qiskit Gym server only (community)

# Install community servers only
pip install qiskit-mcp-servers[community]

Install from Source

Each server is designed to run independently. Choose the server you need:

🔬 Qiskit Server

cd qiskit-mcp-server
uv run qiskit-mcp-server

🧠 Qiskit Code Assistant Server

cd qiskit-code-assistant-mcp-server
uv run qiskit-code-assistant-mcp-server

⚙️ IBM Runtime Server

cd qiskit-ibm-runtime-mcp-server
uv run qiskit-ibm-runtime-mcp-server

🚀 IBM Transpiler Server

cd qiskit-ibm-transpiler-mcp-server
uv run qiskit-ibm-transpiler-mcp-server

📚 Documentation Server

cd qiskit-docs-mcp-server
uv run qiskit-docs-mcp-server

🏋️ Qiskit Gym Server (Community)

cd qiskit-gym-mcp-server
uv run qiskit-gym-mcp-server

🔧 Configuration

Environment Variables

# For IBM Runtime Server
export QISKIT_IBM_TOKEN="your_ibm_quantum_token_here"

# For Code Assistant Server  
export QISKIT_IBM_TOKEN="your_ibm_quantum_token_here"
export QCA_TOOL_API_BASE="https://qiskit-code-assistant.quantum.ibm.com"

Using with MCP Clients

All servers are compatible with any MCP client. Test interactively with MCP Inspector:

# Replace <server-name> with any server command
npx @modelcontextprotocol/inspector uv run qiskit-mcp-server
npx @modelcontextprotocol/inspector uv run qiskit-docs-mcp-server
npx @modelcontextprotocol/inspector uv run qiskit-ibm-runtime-mcp-server
# etc.

Claude Desktop / Cline Configuration

Add to your MCP client configuration (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "qiskit": {
      "command": "uvx",
      "args": ["qiskit-mcp-server"]
    },
    "qiskit-docs": {
      "command": "uvx",
      "args": ["qiskit-docs-mcp-server"]
    },
    "qiskit-runtime": {
      "command": "uvx",
      "args": ["qiskit-ibm-runtime-mcp-server"],
      "env": {
        "QISKIT_IBM_TOKEN": "your_ibm_quantum_token_here"
      }
    }
  }
}

See each server's README for the full list of environment variables and configuration options.

🏗️ Architecture & Design

🎯 Unified Design Principles

All servers follow a consistent, production-ready architecture:

• 🔄 Async-first: Built with FastMCP for high-performance async operations
• 🧪 Test-driven: Comprehensive test suites with 65%+ coverage
• 🛡️ Type-safe: Full mypy type checking and validation
• 📦 Modern packaging: Standard pyproject.toml with hatchling build system
• 🔧 Developer-friendly: Automated formatting (ruff), linting, and CI/CD

🔌 MCP Protocol Support

All servers implement the full Model Context Protocol specification:

• 🛠️ Tools: Execute quantum operations (code completion, job submission, backend queries)
• 📚 Resources: Access quantum data (service status, backend information, model details)
• ⚡ Real-time: Async operations for responsive AI interactions
• 🔒 Secure: Proper authentication and error handling

🧪 Development

🏃‍♂️ Running Tests

# Run tests for any server
cd qiskit-code-assistant-mcp-server  # or any server directory
./run_tests.sh

🔍 Code Quality

All servers maintain high code quality standards:

• ✅ Linting: ruff check and ruff format
• 🛡️ Type checking: mypy src/
• 🧪 Testing: pytest with async support and coverage reporting
• 🚀 CI/CD: GitHub Actions for automated testing

📖 Resources & Documentation

🔗 Essential Links

• Model Context Protocol - Understanding MCP
• Qiskit IBM Runtime - Quantum cloud services
• Qiskit Code Assistant - AI code assistance
• MCP Inspector - Interactive testing tool
• FastMCP - High-performance MCP framework

AI Development Assistant Support

This repository includes AI-generated code and offers comprehensive guidance for AI coding assistants (like IBM Bob, Claude Code, GitHub Copilot, Cursor AI, and others) in AGENTS.md. This helps AI assistants provide more accurate, context-aware suggestions when working with this codebase.

📄 License

This project is licensed under the Apache License 2.0.