{"id":27256062,"url":"https://github.com/yuchenssr/quantum-simulator-mcp","last_synced_at":"2025-10-12T06:18:26.856Z","repository":{"id":283819849,"uuid":"952994226","full_name":"YuChenSSR/quantum-simulator-mcp","owner":"YuChenSSR","description":"for quantum computing","archived":false,"fork":false,"pushed_at":"2025-03-22T11:13:26.000Z","size":4,"stargazers_count":9,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-17T13:15:24.923Z","etag":null,"topics":["openqasm","quantum-computing"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/YuChenSSR.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-22T10:22:20.000Z","updated_at":"2025-04-05T08:37:38.000Z","dependencies_parsed_at":"2025-03-22T12:19:00.546Z","dependency_job_id":"a0add70e-5620-4281-81e4-d0a27a87f2e7","html_url":"https://github.com/YuChenSSR/quantum-simulator-mcp","commit_stats":null,"previous_names":["yuchenssr/quantum-simulator-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/YuChenSSR/quantum-simulator-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YuChenSSR%2Fquantum-simulator-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YuChenSSR%2Fquantum-simulator-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YuChenSSR%2Fquantum-simulator-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YuChenSSR%2Fquantum-simulator-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/YuChenSSR","download_url":"https://codeload.github.com/YuChenSSR/quantum-simulator-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YuChenSSR%2Fquantum-simulator-mcp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267371399,"owners_count":24076596,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["openqasm","quantum-computing"],"created_at":"2025-04-11T02:49:11.750Z","updated_at":"2025-10-12T06:18:21.809Z","avatar_url":"https://github.com/YuChenSSR.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Quantum Simulator MCP Server\n\nA Docker image providing a quantum circuit simulator that implements the Model Context Protocol (MCP), allowing integration with MCP clients such as Claude for Desktop.\n\n\n\n## Features\n\n- Quantum computing simulator with noise models\n- Support for OpenQASM 2.0 quantum circuits\n- Quantum circuit simulation using Qiskit\n- Support for various noise models (depolarizing, thermal relaxation, readout error)\n- Multiple result types including counts, statevector, and visualized histograms\n- Pre-configured example circuits\n- Seamless integration with MCP clients\n\n## Quick Start\n\nget the docker image\n\n```bash\ndocker pull ychen94/quantum-simulator-mcp:latest\n```\n\n\nSimply run the container with the following command:\n\n```bash\ndocker run -i --rm -v /tmp:/data/quantum_simulator_results -e HOST_OUTPUT_DIR=\"/tmp\" ychen94/quantum-simulator-mcp:latest\n```\n\nThis command:\n- Mounts the `/tmp` directory on your host to store histogram output files\n- Sets the `HOST_OUTPUT_DIR` environment variable to `/tmp`\n- Keeps the container running with `-i` (interactive mode)\n- Automatically removes the container when it exits with `--rm`\n\n## Using with Claude for Desktop\n\n1. Install Claude for Desktop\n2. Edit the Claude configuration file:\n   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n3. Add the following configuration to the `mcpServers` section:\n\n```json\n{\n  \"mcpServers\": {\n    \"quantum-simulator\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"-i\",\n        \"--rm\",\n        \"-v\", \"/tmp:/data/quantum_simulator_results\",\n        \"-e\", \"HOST_OUTPUT_DIR=/tmp\",\n        \"ychen94/quantum-simulator-mcp:latest\"\n      ]\n    }\n  }\n}\n```\n\n4. Restart Claude for Desktop\n5. Look for the hammer icon in the Claude UI, indicating available MCP tools\n\n## MCP Tools\n\nThe server provides the following MCP tools:\n\n- **run_circuit**: Run a quantum circuit with specified noise model\n- **list_noise_models**: List all available noise models and their descriptions\n- **list_result_types**: List all available result types and their descriptions\n- **get_circuit_stats**: Analyze a quantum circuit and return statistics\n- **create_test_histogram**: Create a test histogram file to verify output directory configuration\n\n## MCP Resources\n\nThe server provides example quantum circuits:\n\n- `qasm://examples/bell-state.qasm`: Bell state preparation circuit\n- `qasm://examples/grover-2qubit.qasm`: 2-qubit Grover's algorithm implementation\n- `qasm://examples/qft-4qubit.qasm`: 4-qubit Quantum Fourier Transform\n- `quantum://noise-models/examples.json`: Example noise model configurations\n\n## Example Usage in Claude\n\nHere are some prompts you can use in Claude:\n\n1. \"Run a Bell state circuit and show me the results\"\n\n2. \"What noise models are available in the quantum simulator?\"\n\n3. \"Simulate a 2-qubit Grover's algorithm with 0.01 depolarizing noise\"\n\n4. \"Create a test histogram and show me the file path\"\n\n5. \"Please provide a simple QAOA algorithm, only get the result_types: histogram, and view the histogram using iterm\"\n\n![chat](https://raw.githubusercontent.com/YuChenSSR/pics/master/imgs/2025-03-22/FHE8cIDqLRN36pOm.png)\n\n![result_pic](https://raw.githubusercontent.com/YuChenSSR/pics/master/imgs/2025-03-22/OKD2nqE0aHYuWBan.png)\n\n\n## Volume Mapping\n\nThe 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.\n\n## Environment Variables\n\n- `QUANTUM_OUTPUT_DIR`: Output directory for histogram files inside the container (default: `/data/quantum_simulator_results`)\n- `HOST_OUTPUT_DIR`: Corresponding path on the host system (default: `/tmp`)\n\n## Multi-Architecture Support\n\nThis image supports the following architectures:\n- linux/amd64\n- linux/arm64 (confirmed working on Mac M-series chips)\n\nNote: The image has not been tested on Windows systems yet, but should work as long as Docker Desktop is properly configured.\n\n## Troubleshooting\n\n**Issue**: Claude cannot access the histogram files.  \n**Solution**: Ensure the volume mapping is correct and the `HOST_OUTPUT_DIR` environment variable matches the host path in your volume mapping.\n\n**Issue**: Docker container exits immediately.  \n**Solution**: Make sure to use the `-i` flag to keep stdin open, which is required for the MCP STDIO transport.\n\n## License\n\nThis 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).\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuchenssr%2Fquantum-simulator-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyuchenssr%2Fquantum-simulator-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuchenssr%2Fquantum-simulator-mcp/lists"}