{"id":30805528,"url":"https://github.com/aaronsb/ibm-quantum-mcp","last_synced_at":"2025-09-06T00:58:48.382Z","repository":{"id":300311861,"uuid":"1005843429","full_name":"aaronsb/ibm-quantum-mcp","owner":"aaronsb","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-21T00:44:56.000Z","size":92,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-21T01:35:30.222Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aaronsb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2025-06-20T23:37:17.000Z","updated_at":"2025-06-21T00:44:59.000Z","dependencies_parsed_at":"2025-06-21T01:35:37.178Z","dependency_job_id":"990c720b-2f7d-4d77-916d-a301281f5ba2","html_url":"https://github.com/aaronsb/ibm-quantum-mcp","commit_stats":null,"previous_names":["aaronsb/ibm-quantum-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aaronsb/ibm-quantum-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fibm-quantum-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fibm-quantum-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fibm-quantum-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fibm-quantum-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aaronsb","download_url":"https://codeload.github.com/aaronsb/ibm-quantum-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fibm-quantum-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273842828,"owners_count":25177921,"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-09-05T02:00:09.113Z","response_time":402,"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":[],"created_at":"2025-09-06T00:58:45.310Z","updated_at":"2025-09-06T00:58:48.366Z","avatar_url":"https://github.com/aaronsb.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Qiskit VQE MCP Servers\n\nMCP (Model Context Protocol) servers that enable AI assistants like Claude to perform quantum computing experiments using IBM Quantum hardware and local simulators.\n\n## Overview\n\nThis proof-of-concept demonstrates how to make quantum computing accessible through conversational AI. The project provides two specialized MCP servers:\n\n1. **Local Simulation Server** (`mcp_vqe_server_local.py`) - Fast, always-available quantum simulations\n2. **Quantum Hardware Server** (`mcp_vqe_server_quantum.py`) - Access to real IBM Quantum processors\n\n## Current Status: Proof of Concept\n\nThis is an early-stage implementation where the VQE algorithm code is embedded directly within each MCP server. While functional, this architecture has limitations for scaling. The simulation and hardware servers duplicate significant code, making maintenance and feature additions challenging.\n\n### Architectural Considerations\n\nFor production use or expansion beyond VQE, consider:\n- **Shared quantum algorithm library** - Extract VQE and other algorithms into a separate module\n- **Abstract quantum backend interface** - Allow switching between simulators and hardware without code duplication\n- **Plugin architecture** - Enable adding new algorithms without modifying server code\n- **Result caching layer** - Store expensive quantum computations for reuse\n\n## Features\n\n- 🧪 Run Variational Quantum Eigensolver (VQE) for molecular energy calculations\n- 🔬 Support for H₂ and HeH⁺ molecules (easily extensible)\n- 📊 Real-time convergence tracking with matplotlib visualizations\n- 🖥️ Access to IBM's latest Heron R2 quantum processors (156 qubits)\n- 🛡️ Built-in error mitigation and transpilation optimization\n- 📈 Job tracking and result retrieval from IBM Quantum\n\n## Quick Start\n\n1. **Install dependencies:**\n   ```bash\n   pip install uv\n   uv sync\n   ```\n\n2. **Set up IBM Quantum credentials (for hardware access):**\n   ```bash\n   cp .env.example .env\n   # Edit .env with your IBM Quantum API key\n   ```\n\n3. **Register with Claude:**\n   ```bash\n   # Local simulation (no credentials needed)\n   claude mcp add qiskit-vqe-local \"uv\" \"--directory\" \"$(pwd)\" \"run\" \"python\" \"mcp_vqe_server_local.py\"\n   \n   # Quantum hardware (requires IBM credentials)\n   claude mcp add qiskit-vqe-quantum \"uv\" \"--directory\" \"$(pwd)\" \"run\" \"python\" \"mcp_vqe_server_quantum.py\"\n   ```\n\n## Project Structure\n\n```\nqiskit/\n├── mcp_vqe_server_local.py    # Local quantum simulator\n├── mcp_vqe_server_quantum.py  # IBM Quantum hardware interface\n├── CLAUDE.md                  # Project context for AI assistants\n├── .env.example               # Template for IBM credentials\n├── pyproject.toml             # Python dependencies\n└── vqe_plots/                 # Generated convergence plots\n```\n\n## Example Results\n\n### Local Simulation (Ideal)\n- H₂ Energy: -1.857 Hartree\n- Error: 0.002 Hartree\n- Time: \u003c1 second\n\n### IBM Quantum Hardware (Real)\n- H₂ Energy: -1.728 Hartree\n- Error: 0.127 Hartree\n- Backend: IBM Torino (156 qubits)\n- Time: ~30 seconds + queue\n\n## Documentation\n\nFor the full story of this project, including technical details and the journey of building it, see the comprehensive report in the TeXFlow project: `quantum_journey_report.pdf`\n\n## Future Enhancements: Quantum Circuit Lego Blocks\n\nThe next evolution of this MCP server would be to expose IBM's full suite of quantum primitives, circuits, and operators as modular \"Lego blocks\" that can be assembled through conversation:\n\n### Proposed Additions\n\n1. **Standard Circuit Library**\n   - Quantum Fourier Transform (QFT)\n   - Grover's Algorithm components\n   - Quantum Phase Estimation\n   - QAOA mixers and cost operators\n   - Quantum arithmetic circuits\n\n2. **Advanced Primitives**\n   - Sampler for probability distributions\n   - Extended Estimator options\n   - Statevector access for debugging\n   - Noise model simulation\n\n3. **Quantum Operators**\n   - Pauli operators and combinations\n   - Fermionic operators\n   - Spin operators\n   - Custom Hamiltonian builders\n\n4. **Circuit Building Tools**\n   - Gate sequence optimization\n   - Entanglement generation patterns\n   - State preparation routines\n   - Measurement optimization\n\n5. **Utility Functions**\n   - Circuit depth analysis\n   - Gate count optimization\n   - Connectivity mapping\n   - Error rate estimation\n\n### Example Future Usage\n\n```\nUser: \"Create a 4-qubit GHZ state and measure correlations\"\nClaude: [Assembles GHZ circuit, runs on quantum hardware, analyzes results]\n\nUser: \"Build a quantum adder for 3-bit numbers\"\nClaude: [Constructs arithmetic circuit using standard components]\n\nUser: \"Implement Grover's algorithm to search for |101⟩\"\nClaude: [Builds oracle and diffusion operators, executes search]\n```\n\nThis modular approach would make quantum computing as accessible as building with blocks, allowing rapid prototyping of quantum algorithms through natural conversation.\n\n## License\n\nMIT License - Feel free to experiment and extend!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronsb%2Fibm-quantum-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaronsb%2Fibm-quantum-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronsb%2Fibm-quantum-mcp/lists"}