Qiskit IBM Runtime MCP Server — Claude Code MCP server: guide
Connects AI assistants to IBM Quantum computing hardware via Qiskit IBM Runtime. Useful for running quantum circuits, tracking jobs, and inspecting backend calibration in chat.
claude mcp add --env QISKIT_IBM_TOKEN=<QISKIT_IBM_TOKEN> --env QISKIT_IBM_RUNTIME_MCP_INSTANCE=<QISKIT_IBM_RUNTIME_MCP_INSTANCE> --transport stdio qiskit-ibm-runtime-mcp-server -- uvx qiskit-ibm-runtime-mcp-serverWhat Qiskit IBM Runtime MCP Server does
This server connects AI coding agents to IBM Quantum backends through the Model Context Protocol. It allows assistants to run quantum programs, inspect physical device properties, and retrieve measurement counts without manual notebook setup.
Execution relies on EstimatorV2 for expectation values and SamplerV2 for probability distributions. The server analyzes hardware calibration data to find optimal qubit chains for linear layouts. You can also monitor active jobs, read final outputs, or abort queue entries directly.
You need Python 3.10 or higher and an active IBM Quantum API token. Omitting the QISKIT_IBM_RUNTIME_MCP_INSTANCE variable forces a slow discovery pass across all account instances, delaying startup.
What it helps with
- run quantum circuits with EstimatorV2 and SamplerV2 primitives
- find the least busy IBM Quantum backend
- identify optimal qubit chains using hardware calibration data
- track execution status and fetch completed job results
- cancel pending quantum jobs from the queue
Example prompts for the agent
- Show the least busy IBM Quantum backend and fetch its current calibration parameters.
- Find the best 5-qubit chain on the least busy device for a linear experiment.
- Check the status of my recent quantum job and print the measurement counts if it finished.
How to install Qiskit IBM Runtime MCP Server
Platform CLI
claude mcp add --env QISKIT_IBM_TOKEN=<QISKIT_IBM_TOKEN> --env QISKIT_IBM_RUNTIME_MCP_INSTANCE=<QISKIT_IBM_RUNTIME_MCP_INSTANCE> --transport stdio qiskit-ibm-runtime-mcp-server -- uvx qiskit-ibm-runtime-mcp-serverReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from qiskit-ibm-runtime-mcp-server <command>
Platform CLI
codex mcp add qiskit-ibm-runtime-mcp-server --env QISKIT_IBM_TOKEN=<QISKIT_IBM_TOKEN> --env QISKIT_IBM_RUNTIME_MCP_INSTANCE=<QISKIT_IBM_RUNTIME_MCP_INSTANCE> -- uvx qiskit-ibm-runtime-mcp-serverReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from qiskit-ibm-runtime-mcp-server <command>
Config file
{
"mcpServers": {
"qiskit-ibm-runtime-mcp-server": {
"command": "uvx",
"args": [
"qiskit-ibm-runtime-mcp-server"
],
"env": {
"QISKIT_IBM_TOKEN": "<QISKIT_IBM_TOKEN>",
"QISKIT_IBM_RUNTIME_MCP_INSTANCE": "<QISKIT_IBM_RUNTIME_MCP_INSTANCE>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from qiskit-ibm-runtime-mcp-server <command>
Config file
{
"servers": {
"qiskit-ibm-runtime-mcp-server": {
"type": "stdio",
"command": "uvx",
"args": [
"qiskit-ibm-runtime-mcp-server"
],
"env": {
"QISKIT_IBM_TOKEN": "<QISKIT_IBM_TOKEN>",
"QISKIT_IBM_RUNTIME_MCP_INSTANCE": "<QISKIT_IBM_RUNTIME_MCP_INSTANCE>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from qiskit-ibm-runtime-mcp-server <command>
Platform CLI
gemini mcp add -e QISKIT_IBM_TOKEN=<QISKIT_IBM_TOKEN> -e QISKIT_IBM_RUNTIME_MCP_INSTANCE=<QISKIT_IBM_RUNTIME_MCP_INSTANCE> qiskit-ibm-runtime-mcp-server uvx qiskit-ibm-runtime-mcp-serverReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from qiskit-ibm-runtime-mcp-server <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Qiskit IBM Runtime MCP Server
How do I install Qiskit IBM Runtime MCP Server in Claude Code?
Run `claude mcp add --env QISKIT_IBM_TOKEN=<QISKIT_IBM_TOKEN> --env QISKIT_IBM_RUNTIME_MCP_INSTANCE=<QISKIT_IBM_RUNTIME_MCP_INSTANCE> --transport stdio qiskit-ibm-runtime-mcp-server -- uvx qiskit-ibm-runtime-mcp-server`. Replace the placeholders with your actual token and instance CRN.
What does Qiskit IBM Runtime MCP Server do?
It exposes IBM Quantum services to AI assistants. The server handles circuit execution, job management, and backend calibration queries over the Model Context Protocol.
Why should I configure QISKIT_IBM_RUNTIME_MCP_INSTANCE?
Setting this variable specifies your instance CRN directly. Without it, the client runs a slow discovery scan across all instances associated with your account on startup.
