{"id":48419251,"url":"https://github.com/daedalus/mcp-qiskit","last_synced_at":"2026-04-06T08:00:36.647Z","repository":{"id":349448692,"uuid":"1202364994","full_name":"daedalus/mcp-qiskit","owner":"daedalus","description":"MCP server exposing Qiskit 2.3.1 quantum computing functionality through the Model Context Protocol. Enables LLMs to create, manipulate, and execute quantum circuits via standardized MCP tools and resources.","archived":false,"fork":false,"pushed_at":"2026-04-06T01:53:25.000Z","size":29,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-06T02:28:32.597Z","etag":null,"topics":["mcp","qiskit","quantum-computing"],"latest_commit_sha":null,"homepage":"","language":"Python","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/daedalus.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-06T00:09:59.000Z","updated_at":"2026-04-06T01:53:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/daedalus/mcp-qiskit","commit_stats":null,"previous_names":["daedalus/mcp-qiskit"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/daedalus/mcp-qiskit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daedalus%2Fmcp-qiskit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daedalus%2Fmcp-qiskit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daedalus%2Fmcp-qiskit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daedalus%2Fmcp-qiskit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daedalus","download_url":"https://codeload.github.com/daedalus/mcp-qiskit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daedalus%2Fmcp-qiskit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31464097,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T21:22:52.476Z","status":"online","status_checked_at":"2026-04-06T02:00:07.287Z","response_time":112,"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":["mcp","qiskit","quantum-computing"],"created_at":"2026-04-06T08:00:30.820Z","updated_at":"2026-04-06T08:00:36.618Z","avatar_url":"https://github.com/daedalus.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mcp-qiskit\n\nMCP server exposing Qiskit 2.3.1 quantum computing functionality through the Model Context Protocol. Enables LLMs to create, manipulate, and execute quantum circuits via standardized MCP tools and resources.\n\n[![PyPI](https://img.shields.io/pypi/v/mcp-qiskit.svg)](https://pypi.org/project/mcp-qiskit/)\n[![Python](https://img.shields.io/pypi/pyversions/mcp-qiskit.svg)](https://pypi.org/project/mcp-qiskit/)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![Tests](https://github.com/daedalus/mcp-qiskit/actions/workflows/ci.yml/badge.svg)](https://github.com/daedalus/mcp-qiskit/actions)\n\nmcp-name: io.github.daedalus/mcp-qiskit\n\n## Overview\n\nThis project provides a Model Context Protocol (MCP) server that exposes [Qiskit](https://qiskit.com/) quantum computing functionality to Large Language Models (LLMs). It allows AI assistants to:\n\n- Create and manipulate quantum circuits\n- Execute circuits on quantum simulators or real backends\n- Analyze circuit properties (depth, gates, operations)\n- Visualize circuits in various formats\n- Manage quantum backends\n\n### Why Use This?\n\n- **LLM Integration**: Enables AI assistants to perform quantum computing tasks without external tooling\n- **Standardized Interface**: MCP provides a consistent tool-based interface for quantum operations\n- **Qiskit 2.3.1 Compatible**: Specifically designed for Qiskit 2.3.1 with all its features\n- **Extensible**: Easy to add new tools or backends\n\n## Installation\n\n### Prerequisites\n\n- Python 3.11 or higher\n- Qiskit 2.3.1\n- A running MCP client (Claude Desktop, Cursor, etc.)\n\n### Install from PyPI\n\n```bash\npip install mcp-qiskit[qiskit]\n```\n\nThe `[qiskit]` extra installs the required Qiskit dependencies. Other extras available:\n\n```bash\n# Install with development dependencies\npip install mcp-qiskit[dev,test]\n\n# Install with MCP server dependencies\npip install mcp-qiskit[mcp]\n```\n\n### Install from Source\n\n```bash\ngit clone https://github.com/daedalus/mcp-qiskit.git\ncd mcp-qiskit\npip install -e \".[all]\"\n```\n\n## Quick Start\n\n### As a Python Library\n\n```python\nfrom mcp_qiskit import create_quantum_circuit, add_gate, add_gates, add_measurement, run_circuit\n\n# Create a 2-qubit circuit with 2 classical bits\ncircuit = create_quantum_circuit(2, 2)\n\n# Apply a Hadamard gate on qubit 0\ncircuit = add_gate(circuit, \"h\", [0])\n\n# Apply CNOT gate (control: qubit 0, target: qubit 1)\ncircuit = add_gate(circuit, \"cx\", [0, 1])\n\n# Or add multiple gates at once with add_gates\ncircuit = add_gates(circuit, [\n    {\"gate\": \"h\", \"qubits\": [0]},\n    {\"gate\": \"cx\", \"qubits\": [0, 1]},\n])\n\n# Measure all qubits\ncircuit = add_measurement(circuit, [0, 1])\n\n# Execute on Aer simulator\nresult = run_circuit(circuit, \"aer_simulator\", shots=1024)\nprint(f\"Measurement results: {result['counts']}\")\n```\n\n### As an MCP Server\n\n#### Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-qiskit\": {\n      \"command\": \"mcp-qiskit\",\n      \"env\": {}\n    }\n  }\n}\n```\n\n#### Cursor\n\nAdd to your Cursor settings under MCP Servers:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-qiskit\": {\n      \"command\": \"mcp-qiskit\",\n      \"args\": []\n    }\n  }\n}\n```\n\n#### Other MCP Clients\n\n```bash\n# Run as stdio server\nmcp-qiskit\n\n# Or use the Python module directly\npython -m mcp_qiskit\n```\n\n## MCP Tools Reference\n\n### Circuit Creation Tools\n\n#### create_quantum_circuit_tool\n\nCreates an empty quantum circuit with specified number of qubits and classical bits.\n\n**Parameters:**\n- `num_qubits` (int): Number of quantum bits\n- `num_classical_bits` (int): Number of classical bits for measurements\n\n**Returns:** Dictionary representing the circuit\n\n**Example:**\n```python\ncircuit = create_quantum_circuit_tool(num_qubits=3, num_classical_bits=3)\n# Returns: {\"num_qubits\": 3, \"num_clbits\": 3, \"operations\": [], \"name\": \"circuit\"}\n```\n\n#### add_gate_tool\n\nAdds a quantum gate to a circuit. **This tool maintains circuit state between calls.**\n\n**Parameters:**\n- `circuit` (dict, optional): The circuit to modify. If None, creates a new 8-qubit circuit with 8 classical bits automatically.\n- `gate_name` (str): Name of the gate (e.g., \"h\", \"x\", \"cx\", \"rx\")\n- `qubits` (list[int]): List of qubit indices to apply the gate to. Can be a single qubit (e.g., `[0]`) or multiple qubits (e.g., `[0, 1, 2, 3]`). When multiple qubits are specified for a single-qubit gate, the gate is applied to each qubit.\n- `params` (list[float], optional): Parameters for parameterized gates\n\n**Supported Gates:**\n- Single-qubit: `h`, `x`, `y`, `z`, `s`, `t`, `sdg`, `tdg`, `i`, `id`\n- Parameterized: `rx`, `ry`, `rz`, `u1`, `u2`, `u3`, `p`\n- Multi-qubit: `cx`, `cy`, `cz`, `swap`\n- Multi-controlled: `mcx`, `mct`, `mcp`, `ccx`, `toffoli`, `c3x`, `c3sx`, `c4x`\n- Specialized: `rxx`, `ryy`, `rzz`, `ch`, `cswap`, `cu`, `crx`, `cry`, `crz`\n\n**State Maintenance Pattern:**\nAlways pass the circuit returned by the previous call to maintain state:\n\n```python\n# Option 1: Pass circuit explicitly\ncircuit = add_gate_tool(circuit=None, gate_name=\"h\", qubits=[0])  # Creates new circuit\ncircuit = add_gate_tool(circuit=circuit, gate_name=\"x\", qubits=[1])  # Appends\n\n# Option 2: Use returned circuit\ncircuit = add_gate_tool(None, \"h\", [0])\ncircuit = add_gate_tool(circuit, \"cx\", [0, 1])\ncircuit = add_gate_tool(circuit, \"rx\", [0], [0.5])\n```\n\n**Apply Single-Quantum Gate to Multiple Qubits:**\nWhen applying single-qubit gates (like `h`, `x`, `y`, `z`, etc.) to multiple qubits at once, use a list of qubit indices:\n\n```python\n# Apply H gate to qubits 0, 1, 2, 3 simultaneously\ncircuit = add_gate_tool(circuit, \"h\", [0, 1, 2, 3])\n\n# Apply X gate to qubits 4, 5, 6, 7 simultaneously  \ncircuit = add_gate_tool(circuit, \"x\", [4, 5, 6, 7])\n```\n\n#### add_gates_tool\n\nAdds multiple quantum gates to a circuit in a single call. **This tool maintains circuit state between calls and reduces the number of tool calls needed.**\n\n**Parameters:**\n- `circuit` (dict, optional): The circuit to modify. If None, creates a new 8-qubit circuit with 8 classical bits automatically.\n- `gates` (list[dict]): List of gate specifications, each containing:\n  - `gate` (str): Name of the gate (e.g., \"h\", \"x\", \"cx\", \"rx\")\n  - `qubits` (list[int]): Qubit indices to apply the gate to\n  - `params` (list[float], optional): Parameters for parameterized gates\n\n**Example:**\n```python\n# Add multiple gates in one call (reduces tool calls)\ngates = [\n    {\"gate\": \"h\", \"qubits\": [0]},\n    {\"gate\": \"cx\", \"qubits\": [0, 1]},\n    {\"gate\": \"x\", \"qubits\": [2]},\n]\ncircuit = add_gates_tool(circuit=None, gates=gates)\n\n# Can be chained to maintain state\ncircuit = add_gates_tool(None, [{\"gate\": \"h\", \"qubits\": [0, 1]}])\ncircuit = add_gates_tool(circuit, [{\"gate\": \"rz\", \"qubits\": [0], \"params\": [0.5]}])\n```\n\n#### add_measurement_tool\n\nAdds measurement operations to qubits. **This tool maintains circuit state between calls.**\n\n**Parameters:**\n- `circuit` (dict, optional): The circuit to modify. If None, creates a new 8-qubit circuit with 8 classical bits automatically.\n- `qubits` (list[int]): Qubit indices to measure\n- `clbits` (list[int], optional): Classical bit indices to store results\n\n**Example:**\n```python\n# Maintain state between calls\ncircuit = add_measurement_tool(circuit=None, qubits=[0, 1])           # Creates new circuit\ncircuit = add_measurement_tool(circuit=circuit, qubits=[2])          # Appends measurement\n\n# Or use returned circuit\ncircuit = add_measurement_tool(None, [0, 1])           # Measure q0-\u003ec0, q1-\u003ec1\ncircuit = add_measurement_tool(circuit, [0, 1], [1, 0]) # Measure q0-\u003ec1, q1-\u003ec0\n```\n\n### Analysis Tools\n\n#### get_circuit_depth_tool\n\nReturns the depth (number of layers) of the circuit.\n\n**Parameters:**\n- `circuit` (dict): The circuit to analyze\n\n**Returns:** Integer representing circuit depth\n\n#### list_available_gates_tool\n\nLists all available quantum gates in Qiskit.\n\n**Returns:** List of gate name strings\n\n#### get_gate_definition_tool\n\nGets detailed information about a quantum gate.\n\n**Parameters:**\n- `gate_name` (str): Name of the gate\n\n**Returns:** Dictionary with gate properties:\n- `name`: Gate name\n- `num_qubits`: Number of qubits the gate operates on\n- `num_parameters`: Number of parameters (0 for fixed gates)\n- `params`: List of parameter values\n\n### Visualization Tools\n\n#### draw_circuit_tool\n\nRenders a circuit in various formats.\n\n**Parameters:**\n- `circuit` (dict): The circuit to draw\n- `output_format` (str): Output format - \"ascii\", \"text\", \"mpl\", \"latex\"\n\n**Returns:** String representation of the circuit\n\n**Example Output (ASCII):**\n```\n     ┌───┐\nq_0: ┤ H ├──■──\n     └───┘┌─┴─┐\nq_1: ────┤ X ├\n         └───┘\nc: 2/═══════╪═══\n         0   1\n```\n\n### Backend Tools\n\n#### list_backends_tool\n\nLists available quantum backends.\n\n**Parameters:**\n- `filters` (dict, optional): Filter criteria (e.g., `{\"status\": \"ONLINE\"}`)\n\n**Returns:** List of backend information dictionaries\n\n#### get_backend_status_tool\n\nGets status information for a backend.\n\n**Parameters:**\n- `backend_name` (str): Name of the backend\n\n**Returns:** Dictionary with:\n- `name`: Backend name\n- `status`: Status (ONLINE/OFFLINE)\n- `num_qubits`: Number of qubits\n\n#### get_backend_configuration_tool\n\nGets detailed configuration for a backend.\n\n**Parameters:**\n- `backend_name` (str): Name of the backend\n\n**Returns:** Dictionary with:\n- `name`: Backend name\n- `num_qubits`: Number of qubits\n- `coupling_map`: Qubit connectivity (if applicable)\n- `basis_gates`: List of available basis gates\n- `max_shots`: Maximum allowed shots\n\n### Execution Tools\n\n#### run_circuit_tool\n\nExecutes a single quantum circuit.\n\n**Parameters:**\n- `circuit` (dict): Circuit to execute\n- `backend_name` (str, optional): Backend name (default: \"aer_simulator\")\n- `shots` (int, optional): Number of measurement shots (default: 1024)\n- `seed` (int, optional): Random seed for reproducibility\n\n**Returns:** Dictionary with:\n- `status`: \"COMPLETED\" or error message\n- `backend`: Backend used\n- `shots`: Number of shots\n- `counts`: Measurement outcome counts (if shots \u003e 0)\n- `statevector`: Statevector (if shots=None)\n- `time_taken`: Execution time in seconds\n\n**Example:**\n```python\nresult = run_circuit_tool(circuit, \"aer_simulator\", shots=1000, seed=42)\n# Returns: {\"status\": \"COMPLETED\", \"counts\": {\"00\": 512, \"11\": 488}, ...}\n```\n\n#### run_circuits_tool\n\nExecutes multiple circuits in a batch.\n\n**Parameters:**\n- `circuits` (list[dict]): List of circuits to execute\n- `backend_name` (str, optional): Backend name\n- `shots` (int, optional): Number of shots\n- `seed` (int, optional): Random seed\n\n**Returns:** List of result dictionaries\n\n**Example:**\n```python\ncircuits = [circuit1, circuit2, circuit3]\nresults = run_circuits_tool(circuits, shots=100)\n# Returns list of 3 result dictionaries\n```\n\n#### transpile_circuit_tool\n\nTranspiles a circuit for optimization or specific backend.\n\n**Parameters:**\n- `circuit` (dict): Circuit to transpile\n- `optimization_level` (int, optional): 0-3 (default: 1)\n- `basis_gates` (list[str], optional): Target basis gates\n\n**Returns:** Transpiled circuit dictionary\n\n**Example:**\n```python\ntranspiled = transpile_circuit_tool(circuit, optimization_level=2)\n```\n\n## MCP Resources\n\n### resource://backends\n\nProvides a list of available quantum backends. Updated dynamically based on available providers.\n\n### resource://gates\n\nProvides a list of all available quantum gates in Qiskit.\n\n## Usage Examples\n\n### Create a Bell State\n\n```python\n# Create 2-qubit circuit\ncircuit = create_quantum_circuit(2, 2)\n\n# Create Bell state: |Φ+⟩ = (|00⟩ + |11⟩) / √2\ncircuit = add_gate(circuit, \"h\", [0])\ncircuit = add_gate(circuit, \"cx\", [0, 1])\ncircuit = add_measurement(circuit, [0, 1])\n\n# Execute\nresult = run_circuit(circuit, \"aer_simulator\", shots=1000)\nprint(result[\"counts\"])  # Approximately {\"00\": 500, \"11\": 500}\n```\n\n### Run Grover's Algorithm\n\n```python\ndef create_grover_circuit(num_qubits, iterations):\n    circuit = create_quantum_circuit(num_qubits, num_qubits)\n    \n    # Initial superposition\n    for i in range(num_qubits):\n        circuit = add_gate(circuit, \"h\", [i])\n    \n    # Grover iterations\n    for _ in range(iterations):\n        # Oracle (marked state |11...1⟩)\n        for i in range(num_qubits):\n            circuit = add_gate(circuit, \"x\", [i])\n        circuit = add_gate(circuit, \"cx\", list(range(num_qubits - 1)), [num_qubits - 1])\n        for i in range(num_qubits):\n            circuit = add_gate(circuit, \"x\", [i])\n        \n        # Diffusion operator\n        for i in range(num_qubits):\n            circuit = add_gate(circuit, \"h\", [i])\n        for i in range(num_qubits):\n            circuit = add_gate(circuit, \"x\", [i])\n        circuit = add_gate(circuit, \"cx\", list(range(num_qubits - 1)), [num_qubits - 1])\n        for i in range(num_qubits):\n            circuit = add_gate(circuit, \"x\", [i])\n        for i in range(num_qubits):\n            circuit = add_gate(circuit, \"h\", [i])\n    \n    # Measurement\n    circuit = add_measurement(circuit, list(range(num_qubits)))\n    return circuit\n\ncircuit = create_grover_circuit(3, 1)\nresult = run_circuit(circuit, \"aer_simulator\", shots=1000)\n```\n\n### Draw and Analyze Circuit\n\n```python\ncircuit = create_quantum_circuit(2, 2)\ncircuit = add_gate(circuit, \"h\", [0])\ncircuit = add_gate(circuit, \"cx\", [0, 1])\ncircuit = add_measurement(circuit, [0, 1])\n\n# Get depth\ndepth = get_circuit_depth(circuit)\nprint(f\"Circuit depth: {depth}\")\n\n# List gates\ngates = list_available_gates()\nprint(f\"Available gates: {len(gates)}\")\n\n# Draw circuit\nascii_output = draw_circuit(circuit, \"ascii\")\nprint(ascii_output)\n```\n\n### Run Shor's Algorithm\n\n```python\nfrom mcp_qiskit import (\n    create_quantum_circuit,\n    add_gate,\n    add_measurement,\n    run_circuit,\n)\n\ndef build_shor_circuit(N=15, a=2, n_count=8):\n    \"\"\"Build Shor's factoring circuit for N=15 using MCX gates.\"\"\"\n    n = N.bit_length()\n    circuit = create_quantum_circuit(n_count + n, n_count)\n    \n    # Superposition on first register\n    for i in range(n_count):\n        circuit = add_gate(circuit, \"h\", [i])\n    \n    # Initialize second register to |1\u003e\n    circuit = add_gate(circuit, \"x\", [n_count])\n    \n    # Controlled modular exponentiation using MCX\n    for i in range(n_count):\n        power = pow(a, 2**i, N)\n        for j in range(n):\n            if (power \u003e\u003e j) \u0026 1:\n                circuit = add_gate(circuit, \"mcx\", [[i], [n_count + j]])\n    \n    # Inverse QFT (simplified)\n    for i in range(n_count - 1, -1, -1):\n        for j in range(i + 1, n_count):\n            circuit = add_gate(circuit, \"cp\", [i, j], [3.14159 / (2 ** (j - i))])\n        circuit = add_gate(circuit, \"h\", [i])\n    \n    # Measure first register\n    circuit = add_measurement(circuit, list(range(n_count)))\n    return circuit\n\n# Run Shor's algorithm to factor 15\ncircuit = build_shor_circuit(N=15, a=2, n_count=8)\nresult = run_circuit(circuit, \"aer_simulator\", shots=1000)\nprint(f\"Results: {result['counts']}\")\n```\n\nSee `examples/shor_example.py` for a complete implementation with factor extraction.\n\n### Shor's Algorithm with MCP Qiskit Tools\n\nBuild Shor's algorithm circuit to factor N=15 using the MCP Qiskit server tools:\n\n```python\n# Step 1: Create an 8-qubit circuit with 4 classical bits\ncircuit = create_quantum_circuit_tool(num_qubits=8, num_classical_bits=4)\n\n# Step 2: Apply H gates to qubits 0-3 (superposition)\ncircuit = add_gate_tool(circuit=circuit, gate_name=\"h\", qubits=[0, 1, 2, 3])\n\n# Step 3: Apply X gates to qubits 4-7 (initialize to |1⟩)\ncircuit = add_gate_tool(circuit=circuit, gate_name=\"x\", qubits=[4, 5, 6, 7])\n\n# Step 4: Add modular exponentiation using CP gates\ncircuit = add_gate_tool(circuit=circuit, gate_name=\"cp\", qubits=[0, 4], params=[3.14159/2])  # CP(π/2)\ncircuit = add_gate_tool(circuit=circuit, gate_name=\"cp\", qubits=[1, 6], params=[3.14159/4])  # CP(π/4)\ncircuit = add_gate_tool(circuit=circuit, gate_name=\"cp\", qubits=[2, 4], params=[3.14159])    # CP(π)\ncircuit = add_gate_tool(circuit=circuit, gate_name=\"cp\", qubits=[3, 4], params=[3.14159])    # CP(π)\n\n# Step 5: Apply inverse QFT using H and CP gates (reverse order)\n# CP(π/4) on [2,3], CP(π/2) on [1,2], CP(π) on [0,1]\ncircuit = add_gate_tool(circuit=circuit, gate_name=\"cp\", qubits=[2, 3], params=[3.14159/4])\ncircuit = add_gate_tool(circuit=circuit, gate_name=\"cp\", qubits=[1, 2], params=[3.14159/2])\ncircuit = add_gate_tool(circuit=circuit, gate_name=\"cp\", qubits=[0, 1], params=[3.14159])\n# H gates in reverse order\ncircuit = add_gate_tool(circuit=circuit, gate_name=\"h\", qubits=[3, 2, 1, 0])\n\n# Step 6: Measure qubits 0-3\ncircuit = add_measurement_tool(circuit=circuit, qubits=[0, 1, 2, 3])\n\n# Step 7: Run on aer_simulator\nresult = run_circuit_tool(circuit=circuit, backend_name=\"aer_simulator\", shots=1024, seed=42)\nprint(f\"Measurement results: {result['counts']}\")\n\n# Extract factors from the measurement result:\n# 1. Compute the phase from measurement outcome\n# 2. Find order r via continued fractions\n# 3. Calculate gcd(a^(r/2) ± 1, N)\n# Expected: Factorization of 15 = 3 × 5\n```\n\n## Architecture\n\n```\nmcp-qiskit/\n├── src/mcp_qiskit/\n│   ├── __init__.py          # Package exports\n│   ├── __main__.py          # CLI entry point\n│   ├── _circuit.py           # Circuit operations\n│   ├── _backend.py           # Backend management\n│   ├── _execution.py         # Circuit execution\n│   └── _mcp.py               # MCP server definition\n├── tests/                    # Test suite\n├── SPEC.md                   # Project specification\n└── README.md                 # This file\n```\n\n### Module Responsibilities\n\n- **_circuit.py**: Quantum circuit creation, gates, measurements, visualization\n- **_backend.py**: Backend discovery, status, configuration\n- **_execution.py**: Circuit execution, transpilation\n- **_mcp.py**: FastMCP server definition, tool registration\n\n## Requirements\n\n- Python 3.11+\n- qiskit \u003e= 2.3.1\n- qiskit-aer \u003e= 0.14.0\n- fastmcp \u003e= 2.0\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/daedalus/mcp-qiskit.git\ncd mcp-qiskit\npip install -e \".[all]\"\n```\n\n### Running Tests\n\n```bash\npytest -v\n```\n\n### Code Quality\n\n```bash\n# Format code\nruff format src/ tests/\n\n# Lint\nruff check src/ tests/\n\n# Type check\nmypy src/\n```\n\n### Pre-commit Hooks\n\n```bash\npre-commit install\n```\n\n## Troubleshooting\n\n### API Keys and Credentials\n\nThis package supports two types of backends:\n\n1. **Aer Simulator** (default) - Runs locally, no API key required\n2. **IBM Quantum** - Requires an IBM Quantum API token\n\n#### Using IBM Quantum Backends\n\nTo use IBM Quantum backends, you need to provide your API token:\n\n**Option 1: Environment Variable**\n\n```bash\nexport IBM_QUANTUM_TOKEN=\"your_api_token_here\"\n```\n\nOr in your Python code:\n\n```python\nimport os\nos.environ[\"IBM_QUANTUM_TOKEN\"] = \"your_api_token_here\"\n```\n\n**Option 2: Save Credentials via Qiskit**\n\n```python\nfrom qiskit_ibm_provider import IBMProvider\n\n# Save your account (only needs to be done once)\nIBMProvider.save_account(token=\"your_api_token_here\", overwrite=True)\n\n# Now you can use IBM backends\nfrom mcp_qiskit._backend import list_backends, get_backend\n\nbackends = list_backends()  # Will include IBM backends\nbackend = get_backend(\"ibm_qasm_simulator\")  # Or specific IBM backend\n```\n\n**Getting an IBM Quantum Token:**\n\n1. Create an account at [IBM Quantum](https://quantum.ibm.com/)\n2. Go to Account \u003e My Tokens\n3. Copy your API token\n\n**Environment Variable for MCP Server:**\n\nWhen running as an MCP server, set the environment variable before starting:\n\n```bash\nexport IBM_QUANTUM_TOKEN=\"your_token\"\nmcp-qiskit\n```\n\nOr in your MCP client configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-qiskit\": {\n      \"command\": \"mcp-qiskit\",\n      \"env\": {\n        \"IBM_QUANTUM_TOKEN\": \"your_token_here\"\n      }\n    }\n  }\n}\n```\n\n### Backend Not Found\n\nIf you get \"Backend not found\", ensure the backend name is correct:\n\n```python\n# List available backends\nbackends = list_backends()\nprint([b[\"name\"] for b in backends])\n```\n\n### Import Errors\n\nMake sure Qiskit is properly installed:\n\n```bash\npip install qiskit==2.3.1 qiskit-aer\n```\n\n### MCP Connection Issues\n\nVerify the server is running:\n\n```bash\nmcp-qiskit --help\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file.\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a PR on GitHub.\n\n## Related Projects\n\n- [Qiskit](https://qiskit.com/) - Quantum computing SDK\n- [FastMCP](https://github.com/jlowin/fastmcp) - MCP framework\n- [Model Context Protocol](https://modelcontextprotocol.io/) - Protocol specification","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaedalus%2Fmcp-qiskit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaedalus%2Fmcp-qiskit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaedalus%2Fmcp-qiskit/lists"}