qiskit-sim-mcp

Claude Desktop이 Qiskit 및 Qiskit Aer를 사용하여 양자 회로를 생성, 시각화 및 시뮬레이션할 수 있도록 하는 MCP(Model Context Protocol) 서버입니다.

기능

Claude Desktop에 연결하면 다음과 같이 자연스럽게 대화할 수 있습니다:

• "벨 상태(Bell state)를 생성하고 1024번의 샷으로 시뮬레이션해 줘"

• "GHZ 회로 다이어그램을 보여줘"

• "높은 노이즈 환경에서 벨 상태를 실행하고 무엇이 바뀌었는지 설명해 줘"

• "이 QASM 문자열로 사용자 지정 회로를 만들어 줘"

Claude가 자동으로 기본 도구를 호출하므로 수동으로 도구를 실행할 필요가 없습니다.

특징

• 3가지 도구: create_circuit, visualize_circuit, run_simulation

• 5가지 사전 설정 회로: Bell state, GHZ-3, Superposition, Deutsch-Jozsa, Random-4

• 사용자 지정 QASM: 유효한 OpenQASM 2.0 문자열 지원

• 노이즈 모델링: 이상적(Ideal), 낮은 노이즈(p=0.001), 높은 노이즈(p=0.01) (탈분극 오류 사용)

• 1가지 리소스: resource://noise-presets — 사용 가능한 노이즈 구성 목록

• 1가지 프롬프트: simulate_walkthrough — 가이드 대화 템플릿

요구 사항

• Python 3.13+

• Anaconda 또는 기타 Python 환경 관리자

• Claude Desktop

설정

1. 저장소 복제

git clone <repo-url>
cd qiskit-sim-mcp

2. 종속성 설치

pip install -e .

이 명령은 Python 환경에 mcp[cli], qiskit 및 qiskit-aer를 설치합니다.

3. 설치 확인

python -c "
import asyncio
from quantum_mcp_demo.server import mcp

tools    = asyncio.run(mcp.list_tools())
resources = asyncio.run(mcp.list_resources())
prompts  = asyncio.run(mcp.list_prompts())

print('Tools:',     [t.name for t in tools])
print('Resources:', [r.uri  for r in resources])
print('Prompts:',   [p.name for p in prompts])
"

예상 출력:

Tools: ['create_circuit', 'visualize_circuit', 'run_simulation']
Resources: [AnyUrl('resource://noise-presets')]
Prompts: ['simulate_walkthrough']

4. MCP Inspector로 테스트 (선택 사항)

uv run mcp dev src/quantum_mcp_demo/server.py

브라우저에서 http://localhost:6274를 엽니다. Claude Desktop에 연결하기 전에 Tools 탭을 사용하여 각 도구를 수동으로 호출해 보세요.

5. Claude Desktop에 연결

Claude Desktop 설정 파일을 찾습니다:

mcpServers 객체 안에 다음 항목을 추가합니다:

{
  "mcpServers": {
    "qiskit-sim-mcp": {
      "command": "/opt/anaconda3/bin/python",
      "args": [
        "-m",
        "quantum_mcp_demo.server"
      ]
    }
  }
}

참고: /opt/anaconda3/bin/python을 실제 Python 경로로 바꾸세요. which python을 실행하여 경로를 찾을 수 있습니다.

6. Claude Desktop 재시작

Claude Desktop을 완전히 종료(macOS의 경우 Cmd+Q)한 후 다시 엽니다. 새 대화에서 채팅 입력창의 망치 아이콘(🔨)이 보이면 MCP 도구가 로드된 것입니다.

사용 예시

벨 상태 시뮬레이션

"벨 상태 회로를 만들고, 다이어그램을 보여준 다음, 이상적인 노이즈와 높은 노이즈 환경에서 각각 1024번 시뮬레이션해 줘."

Claude는 다음을 호출합니다:

1. create_circuit(preset="bell") → circuit_id 획득

2. visualize_circuit(circuit_id=...) → H + CNOT 게이트 다이어그램 표시

3. run_simulation(circuit_id=..., shots=1024, noise_preset="ideal") → ~50% |00⟩, ~50% |11⟩ 결과

4. run_simulation(circuit_id=..., shots=1024, noise_preset="high_noise") → 결과값 저하, |01⟩ 및 |10⟩ 발생

사용자 지정 QASM 회로

"이 회로를 실행해 줘: OPENQASM 2.0; include "qelib1.inc"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;"

Claude가 QASM 문자열을 파싱하여 동일한 시뮬레이션 파이프라인을 통해 실행합니다.

노이즈 비교

"이상적인 상태와 높은 노이즈 상태에서 GHZ 상태를 비교해 줘. 노이즈가 얽힘(entanglement)에 어떤 영향을 미치나요?"

프로젝트 구조

src/quantum_mcp_demo/
├── server.py              # MCP server entry point
├── circuits/
│   ├── presets.py         # 5 named preset circuits
│   └── store.py           # In-memory circuit storage (UUID-keyed)
├── tools/
│   ├── create_circuit.py  # Tool: create from preset or QASM
│   ├── visualize.py       # Tool: HTML diagram + gate JSON
│   └── simulate.py        # Tool: AerSimulator + noise modeling
├── resources/
│   └── noise_presets.py   # Resource: noise configuration list
├── prompts/
│   └── walkthrough.py     # Prompt: guided simulation conversation
└── utils/
    ├── serialization.py   # numpy → Python int conversion
    └── errors.py          # MCP error response builder

사전 설정 회로

노이즈 사전 설정

문제 해결

Claude Desktop에 망치 아이콘이 표시되지 않음

• 설정을 편집한 후 Claude Desktop을 완전히 종료하고 다시 실행하세요.

• 설정 JSON이 유효한지 확인하세요 (마지막 쉼표 금지).

• Python 경로를 확인하세요: which python

python -m quantum_mcp_demo.server 실패

• 프로젝트 루트에서 pip install -e .를 실행했는지 확인하세요.

• Python 버전을 확인하세요: python --version (3.13 이상 필요)

MCP Inspector 실행 시 포트 충돌

kill -9 $(lsof -t -i :6274) 2>/dev/null; kill -9 $(lsof -t -i :6277) 2>/dev/null

시뮬레이션 결과가 예상과 다름

• 샷 횟수 불일치는 자동으로 감지되어 isError: true로 반환됩니다.

• 오류가 발생하면 shots를 줄여보세요 (예: 512).