qiskit-sim-mcp

Un servidor del Protocolo de Contexto de Modelo (MCP) que permite a Claude Desktop crear, visualizar y simular circuitos cuánticos utilizando Qiskit y Qiskit Aer.

Qué hace

Una vez conectado a Claude Desktop, puedes tener conversaciones naturales como:

• "Crea un estado de Bell y simúlalo con 1024 disparos"

• "Muéstrame el diagrama del circuito GHZ"

• "Ejecuta el estado de Bell con mucho ruido y explica qué cambió"

• "Crea un circuito personalizado a partir de esta cadena QASM"

Claude llamará a las herramientas subyacentes automáticamente; no se necesita invocación manual de herramientas.

Características

• 3 herramientas: create_circuit, visualize_circuit, run_simulation

• 5 circuitos preestablecidos: estado de Bell, GHZ-3, superposición, Deutsch-Jozsa, aleatorio-4

• QASM personalizado: Acepta cualquier cadena válida de OpenQASM 2.0

• Modelado de ruido: Ideal, ruido bajo (p=0.001), ruido alto (p=0.01) mediante error de despolarización

• 1 recurso: resource://noise-presets — enumera las configuraciones de ruido disponibles

• 1 prompt: simulate_walkthrough — plantilla de conversación guiada

Requisitos

• Python 3.13+

• Anaconda o cualquier gestor de entornos de Python

• Claude Desktop

Configuración

1. Clonar el repositorio

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

2. Instalar dependencias

pip install -e .

Esto instala mcp[cli], qiskit y qiskit-aer en tu entorno de Python.

3. Verificar la instalación

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])
"

Salida esperada:

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

4. Probar con el Inspector MCP (Opcional)

uv run mcp dev src/quantum_mcp_demo/server.py

Abre http://localhost:6274 en tu navegador. Usa la pestaña Tools para llamar a cada herramienta manualmente antes de conectarte a Claude Desktop.

5. Conectar a Claude Desktop

Busca tu archivo de configuración de Claude Desktop:

Añade esta entrada dentro del objeto mcpServers:

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

Nota: Reemplaza /opt/anaconda3/bin/python con tu ruta real de Python. Ejecuta which python para encontrarla.

6. Reiniciar Claude Desktop

Cierra Claude Desktop por completo (Cmd+Q en macOS), luego vuelve a abrirlo. En una nueva conversación, el icono del martillo (🔨) en la entrada de chat confirma que las herramientas MCP están cargadas.

Ejemplos de uso

Simulación del estado de Bell

"Crea un circuito de estado de Bell, muéstrame el diagrama y luego simúlalo 1024 veces con ruido ideal y alto."

Claude llamará a:

1. create_circuit(preset="bell") → obtiene un circuit_id

2. visualize_circuit(circuit_id=...) → muestra el diagrama de puertas 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") → conteos degradados, aparecen |01⟩ y |10⟩

Circuito QASM personalizado

"Ejecuta este circuito: OPENQASM 2.0; include "qelib1.inc"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;"

Claude analiza la cadena QASM y la ejecuta a través de la misma tubería de simulación.

Comparación de ruido

"Compara el estado GHZ bajo ruido ideal frente a ruido alto: ¿qué le hace el ruido al entrelazamiento?"

Estructura del proyecto

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

Circuitos preestablecidos

Preajustes de ruido

Solución de problemas

Claude Desktop no muestra el icono del martillo

• Cierra y reinicia completamente Claude Desktop después de editar la configuración

• Comprueba que el JSON de configuración sea válido (sin comas finales)

• Verifica la ruta de Python: which python

python -m quantum_mcp_demo.server falla

• Asegúrate de haber ejecutado pip install -e . desde la raíz del proyecto

• Confirma la versión de Python: python --version (necesita 3.13+)

Conflicto de puerto al ejecutar el Inspector MCP

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

La simulación devuelve conteos inesperados

• Los desajustes en el recuento de disparos se detectan automáticamente y se devuelven como isError: true

• Intenta reducir los shots (p. ej., 512) si ves errores