# Directory Structure
```
├── LICENSE
└── README.md
```
# Files
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Quantum Simulator MCP Server
2 |
3 | A Docker image providing a quantum circuit simulator that implements the Model Context Protocol (MCP), allowing integration with MCP clients such as Claude for Desktop.
4 |
5 |
6 |
7 | ## Features
8 |
9 | - Quantum computing simulator with noise models
10 | - Support for OpenQASM 2.0 quantum circuits
11 | - Quantum circuit simulation using Qiskit
12 | - Support for various noise models (depolarizing, thermal relaxation, readout error)
13 | - Multiple result types including counts, statevector, and visualized histograms
14 | - Pre-configured example circuits
15 | - Seamless integration with MCP clients
16 |
17 | ## Quick Start
18 |
19 | get the docker image
20 |
21 | ```bash
22 | docker pull ychen94/quantum-simulator-mcp:latest
23 | ```
24 |
25 |
26 | Simply run the container with the following command:
27 |
28 | ```bash
29 | docker run -i --rm -v /tmp:/data/quantum_simulator_results -e HOST_OUTPUT_DIR="/tmp" ychen94/quantum-simulator-mcp:latest
30 | ```
31 |
32 | This command:
33 | - Mounts the `/tmp` directory on your host to store histogram output files
34 | - Sets the `HOST_OUTPUT_DIR` environment variable to `/tmp`
35 | - Keeps the container running with `-i` (interactive mode)
36 | - Automatically removes the container when it exits with `--rm`
37 |
38 | ## Using with Claude for Desktop
39 |
40 | 1. Install Claude for Desktop
41 | 2. Edit the Claude configuration file:
42 | - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
43 | - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
44 |
45 | 3. Add the following configuration to the `mcpServers` section:
46 |
47 | ```json
48 | {
49 | "mcpServers": {
50 | "quantum-simulator": {
51 | "command": "docker",
52 | "args": [
53 | "run",
54 | "-i",
55 | "--rm",
56 | "-v", "/tmp:/data/quantum_simulator_results",
57 | "-e", "HOST_OUTPUT_DIR=/tmp",
58 | "ychen94/quantum-simulator-mcp:latest"
59 | ]
60 | }
61 | }
62 | }
63 | ```
64 |
65 | 4. Restart Claude for Desktop
66 | 5. Look for the hammer icon in the Claude UI, indicating available MCP tools
67 |
68 | ## MCP Tools
69 |
70 | The server provides the following MCP tools:
71 |
72 | - **run_circuit**: Run a quantum circuit with specified noise model
73 | - **list_noise_models**: List all available noise models and their descriptions
74 | - **list_result_types**: List all available result types and their descriptions
75 | - **get_circuit_stats**: Analyze a quantum circuit and return statistics
76 | - **create_test_histogram**: Create a test histogram file to verify output directory configuration
77 |
78 | ## MCP Resources
79 |
80 | The server provides example quantum circuits:
81 |
82 | - `qasm://examples/bell-state.qasm`: Bell state preparation circuit
83 | - `qasm://examples/grover-2qubit.qasm`: 2-qubit Grover's algorithm implementation
84 | - `qasm://examples/qft-4qubit.qasm`: 4-qubit Quantum Fourier Transform
85 | - `quantum://noise-models/examples.json`: Example noise model configurations
86 |
87 | ## Example Usage in Claude
88 |
89 | Here are some prompts you can use in Claude:
90 |
91 | 1. "Run a Bell state circuit and show me the results"
92 |
93 | 2. "What noise models are available in the quantum simulator?"
94 |
95 | 3. "Simulate a 2-qubit Grover's algorithm with 0.01 depolarizing noise"
96 |
97 | 4. "Create a test histogram and show me the file path"
98 |
99 | 5. "Please provide a simple QAOA algorithm, only get the result_types: histogram, and view the histogram using iterm"
100 |
101 | 
102 |
103 | 
104 |
105 |
106 | ## Volume Mapping
107 |
108 | The container generates histogram PNG files in `/data/quantum_simulator_results`. These files need to be accessible from your host system. The volume mapping (`-v /tmp:/data/quantum_simulator_results`) makes these files available in your host's `/tmp` directory.
109 |
110 | ## Environment Variables
111 |
112 | - `QUANTUM_OUTPUT_DIR`: Output directory for histogram files inside the container (default: `/data/quantum_simulator_results`)
113 | - `HOST_OUTPUT_DIR`: Corresponding path on the host system (default: `/tmp`)
114 |
115 | ## Multi-Architecture Support
116 |
117 | This image supports the following architectures:
118 | - linux/amd64
119 | - linux/arm64 (confirmed working on Mac M-series chips)
120 |
121 | Note: The image has not been tested on Windows systems yet, but should work as long as Docker Desktop is properly configured.
122 |
123 | ## Troubleshooting
124 |
125 | **Issue**: Claude cannot access the histogram files.
126 | **Solution**: Ensure the volume mapping is correct and the `HOST_OUTPUT_DIR` environment variable matches the host path in your volume mapping.
127 |
128 | **Issue**: Docker container exits immediately.
129 | **Solution**: Make sure to use the `-i` flag to keep stdin open, which is required for the MCP STDIO transport.
130 |
131 | ## License
132 |
133 | This project is licensed under the MIT License. For more details, please see the LICENSE file in [this project repository](https://github.com/YuChenSSR/quantum-simulator-mcp).
134 |
135 |
136 |
```