Qiskit Mcp Server

Qiskit MCP Server

非官方 Model Context Protocol（MCP）服务，支持大模型使用 Qiskit 构建和执行量子电路。

功能

该服务提供 13 个 MCP 工具，用于全面的量子电路操作：

核心工具（8 个）

1. create_quantum_circuit

创建包含指定数量量子比特和经典比特的新量子电路。

参数：

• num_qubits（int）：量子比特数量
• num_classical_bits（int，可选）：经典比特数量（默认为 num_qubits）
• name（string，可选）：电路的自定义名称（未提供时自动生成）

2. add_gates

向现有电路添加量子门。

参数：

• circuit_name（string）：要修改的电路名称
• gates（array）：门操作列表

支持的门：

• h：Hadamard 门 - {'type': 'h', 'qubits': [0]}
• x：Pauli-X 门 - {'type': 'x', 'qubits': [0]}
• y：Pauli-Y 门 - {'type': 'y', 'qubits': [0]}
• z：Pauli-Z 门 - {'type': 'z', 'qubits': [0]}
• cx：CNOT 门 - {'type': 'cx', 'qubits': [0, 1]}
• measure：测量指定量子比特 - {'type': 'measure', 'qubits': [0], 'classical_bit': 0}
• measure_all：测量所有量子比特 - {'type': 'measure_all'}

3. run_circuit

在 BasicSimulator 上执行量子电路。

参数：

• circuit_name（string）：要运行的电路名称
• shots（int，可选）：测量次数（默认值：1000）

**返回：**包含测量结果和计数的 JSON

4. get_circuit_info

获取电路的详细信息。

参数：

• circuit_name（string）：电路名称

**返回：**包含电路属性（量子比特、深度、门计数等）的 JSON

5. visualize_circuit

获取量子电路的文本可视化表示。

参数：

• circuit_name（string）：电路名称

**返回：**电路的 ASCII 艺术表示

6. visualize_circuit_mermaid

生成量子电路的 Mermaid 流程图。

参数：

• circuit_name（string）：要可视化的电路名称

**返回：**表示量子电路的 Mermaid 流程图语法

7. list_circuits

列出所有已创建电路及其基本信息。

**返回：**包含所有电路名称及其属性的 JSON

高级工具（6 个）

8. analyze_statevector

分析电路的量子态向量。

参数：

• circuit_name（string）：要分析的电路名称

**返回：**包含概率、振幅和状态分析结果的 JSON

9. compute_density_matrix

计算并分析密度矩阵，包括纯度和纠缠信息。

参数：

• circuit_name（string）：要分析的电路名称

**返回：**包含纯度、熵和纠缠信息的 JSON

10. optimize_circuit

使用 Qiskit 转译器遍次优化量子电路。

参数：

• circuit_name（string）：要优化的电路名称
• optimization_level（int）：优化级别 0-3

**返回：**包含优化结果和性能指标的 JSON

11. add_advanced_gates

添加 H、X、Y、Z、CX 基本门之外的高级量子门。

参数：

• circuit_name（string）：要修改的电路名称
• gates（array）：高级门操作列表

支持的高级门：

• 旋转门：rx、ry、rz、rxx、ryy、rzz
• 通用门：u
• Clifford 门：s、sdg、t、tdg
• swap：SWAP 门

12. create_variational_circuit

创建用于量子机器学习的变分量子电路。

参数：

• num_qubits（int）：量子比特数量
• num_layers（int）：层数（默认值：1）
• entanglement（string）：纠缠模式（'full'、'linear'、'circular'）
• name（string，可选）：电路的自定义名称

**返回：**成功消息，包含电路详情和参数数量

13. implement_qft

实现量子傅里叶变换电路。

参数：

• num_qubits（int）：QFT 的量子比特数
• inverse（bool）：是否实现逆 QFT（默认：false）
• name（string，可选）：电路的自定义名称

返回： 包含 QFT 电路详细信息的成功消息

示例和文档

📚 综合示例

我们提供了丰富的示例和提示词，帮助你快速入门：

• 示例文件夹 - 完整的示例和提示词集合
• 示例 README - 详细指南和学习路径

📋 测试脚本

• 基础操作测试 - 核心 6 个工具的测试用例
• 高级操作测试 - 高级 6 个工具的测试用例
• 量子算法测试 - 著名量子算法

💬 即用提示词（130+ 个示例）

• 基础电路操作 - 面向初学者的提示词
• 高级电路操作 - 状态分析与优化
• 量子算法 - 算法实现
• 教育示例 - 侧重学习的提示词

快速入门示例

创建 Bell 态

Create a 2-qubit quantum circuit and make a Bell state by applying H to qubit 0 and CNOT from 0 to 1, then measure both qubits and run with 1000 shots.

高级状态分析

I have a Bell state circuit. Analyze its statevector to show the probabilities, then compute the density matrix to verify it's entangled with purity=1.0.

电路优化

Create a circuit with redundant gates (X followed by X), then optimize it at level 2 and show me the improvement metrics.

变分量子电路

Create a variational quantum circuit with 4 qubits, 2 layers, and full entanglement for quantum machine learning. Show me how many parameters it has.

运行服务

独立运行

# Install dependencies
uv sync

# Start the MCP server
uv run python main.py

Claude Desktop 集成

将此配置添加到 Claude Desktop 配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%/Claude/claude_desktop_config.json

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

将 /path/to/qiskit-mcp-server 替换为此项目目录的实际路径。

添加配置后，重启 Claude Desktop。然后，你可以让 Claude：

• “创建一个量子 Bell 态电路”
• “为 2 个量子比特构建 Grover 搜索算法”
• “分析我的电路的状态向量以显示纠缠”
• “优化我的电路并展示性能提升”
• “创建一个用于量子机器学习的变分电路”
• “实现一个 3 量子比特的量子傅里叶变换”

测试和验证

运行测试脚本

# Test basic functionality
uv run python examples/test_scripts/test_basic_operations.py

# Test advanced features  
uv run python examples/test_scripts/test_advanced_operations.py

# Test quantum algorithms
uv run python examples/test_scripts/test_quantum_algorithms.py

直接测试（旧版）

uv run python test_direct.py  # If available

依赖项

• qiskit（≥2.1.1）：量子计算框架，包含 quantum_info、circuit.library 和 transpiler 模块
• fastmcp（≥2.10.6）：MCP 服务实现
• numpy：状态分析中数值计算所需

支持的量子计算概念

量子力学基础

• 叠加态：使用 Hadamard 门创建量子叠加态
• 纠缠：使用 CNOT 和高级门创建纠缠态
• 测量：将量子态坍缩为经典比特
• 量子干涉：演示相长干涉和相消干涉

高级量子操作

• 参数化门：使用任意角度进行 RX、RY、RZ 旋转
• 双量子比特旋转：使用 RXX、RYY、RZZ 直接创建纠缠
• 通用量子计算：用于任意量子算法的完备门集
• Clifford 操作：用于量子纠错的 S、T 门

量子态分析

• 状态向量分析：包含概率的完整量子态信息
• 密度矩阵：混合态分析、纯度和熵计算
• 纠缠检测：通过偏迹熵验证量子关联
• 量子态层析：全面表征量子态

量子算法

• 搜索算法：Grover 算法在数据库搜索中实现二次加速
• 判定算法：Deutsch-Jozsa 算法带来指数级优势
• 傅里叶分析：使用量子傅里叶变换查找周期
• 变分算法：VQE、QAOA，用于在近期实现量子优势
• 相位估计：从量子算子中提取特征值和相位

电路优化与分析

• 转译器集成：多级优化（0-3），并提供性能指标
• 电路深度分析：关键路径分析与并行化
• 门数量优化：冗余移除与对易性分析
• 资源估算：算法所需的量子资源

量子机器学习

• 变分电路：使用不同纠缠模式的参数化 ansatz
• 量子特征映射：将经典数据编码为量子态
• 混合算法：经典-量子优化循环

该服务支持大模型通过自然语言描述所需的量子操作，以交互方式构建量子电路；这些描述会被转换为特定的门序列，随后分析量子属性、优化性能，并在量子模拟器上执行，同时全面分析结果。

项目结构

qiskit-mcp-server/
├── main.py                     # MCP server with 13 quantum tools
├── pyproject.toml             # Dependencies and project config
├── examples/                  # Comprehensive examples and documentation
│   ├── README.md             # Learning guide and examples overview  
│   ├── test_scripts/         # Test cases and demonstrations
│   │   ├── test_basic_operations.py      # Core tools testing
│   │   ├── test_advanced_operations.py   # Advanced features testing
│   │   └── test_quantum_algorithms.py    # Algorithm implementations
│   └── prompts/              # 130+ ready-to-use prompt examples
│       ├── basic_circuit_operations.md   # Beginner prompts
│       ├── advanced_circuit_operations.md # State analysis prompts
│       ├── quantum_algorithms.md         # Algorithm prompts
│       └── educational_examples.md       # Learning prompts
└── README.md                  # This file

获取帮助

• 示例：从示例文件夹开始，查看全面指南
• Qiskit 文档：https://qiskit.org/documentation/
• 量子计算学习：IBM Qiskit 教科书
• 问题：通过 GitHub issues 报告错误并请求新功能

贡献

欢迎贡献！可拓展的领域：

• 更多量子算法（Shor 算法、HHL、量子模拟）
• 噪声建模与错误缓解工具
• 高级可视化功能
• 硬件后端集成
• 教育内容与示例

许可证

本项目为开源项目。详情请参阅许可证文件。