FlagQuantum MCP Server

An MCP server that gives any MCP-compatible agent local access to the FlagQuantum SDK: build, compile, route, serialize and plan quantum circuits, with no credentials, no network access and no hardware submission.

Part of FlagQuantum/mcp-servers.

What it does

Nine read-only tools over stdio:

Three resources: flagquantum://version, flagquantum://gate-set, flagquantum://ir-schema.

Three prompts: build_and_analyze_circuit, compile_for_topology, export_circuit.

Install

pip install flagquantum-mcp-server

This pulls flagquantum, which depends on torch.

Claude Code

claude mcp add flagquantum -- uvx flagquantum-mcp-server

Claude Desktop / Cline

{
  "mcpServers": {
    "flagquantum": {
      "command": "uvx",
      "args": ["flagquantum-mcp-server"]
    }
  }
}

MCP Inspector

npx @modelcontextprotocol/inspector uvx flagquantum-mcp-server

Circuit formats

Two input formats are accepted, both of them FlagQuantum's own serialization.

ir (canonical) — FlagQuantum IR JSON, as produced by CircuitIR.to_json(). Versioned, hashable, and rejected if it carries unknown fields:

{
  "kind": "flagquantum.circuit_ir",
  "version": "1.0",
  "n_wires": 2,
  "dtype": "complex64",
  "shape": [4],
  "instructions": [
    {"opcode": "h", "wires": [0], "params": {}, "matrix": null, "metadata": {}},
    {"opcode": "cx", "wires": [0, 1], "params": {}, "matrix": null, "metadata": {}}
  ],
  "observables": [],
  "measurements": [],
  "metadata": {}
}

qir (convenience) — the compact gate list from Circuit.to_qir(), easier to write by hand:

[{"name": "h", "index": [0]}, {"name": "cx", "index": [0, 1]}]

Either format can be passed to any tool; serialize_circuit_tool converts qir into canonical ir.

Limits

Every bound is overridable by environment variable, so a deployment can tighten them without a code change:

Errors

Tools do not raise across the MCP boundary. A failure comes back as:

{"status": "error", "error": {"code": "LIMIT_EXCEEDED", "message": "..."}}

Codes: INVALID_INPUT, LIMIT_EXCEEDED, UNSUPPORTED_FORMAT, SDK_UNAVAILABLE, INTERNAL_ERROR.

What this server deliberately does not do

• No execution. Nothing runs a circuit, locally or remotely. Planning is plan_execution_tool; running is the caller's step, through fq.run.
• No hardware, no credentials, no network. FlagQuantum's own release 0.2.0 ships no remote-submission entry point, and this adapter adds none.
• No noise models. A NoiseModel is a live SDK object rather than a serializable value, and every tool here takes and returns JSON.
• No in-tree coupling. This package must never be imported by the FlagQuantum repository. That project's long-horizon architecture contract names "the main repository has no production MCP transport dependency" as a retirement condition, and its tests/team/services/test_service_boundaries.py fails if mcp or fastmcp becomes importable on the core path. Keeping the gateway out of tree is what that contract asks for.

Which contracts this rests on

FlagQuantum publishes a frozen stable_exports snapshot (34 names, each with a named verification test) and separately describes flagquantum.compiler as its "stable expert compiler interface". This server uses both, in two tiers:

The third tier is the weakest: those two functions are public but are not re-exported from flagquantum.compiler. They are resolved through a helper that turns a relocation into a named error rather than an AttributeError inside a tool call, and tests/test_api_contract.py pins both paths so a move fails the build instead of failing a user.

The dependency is pinned to flagquantum>=0.2,<0.3. It is a version range, never a git URL: a URL in the dependency table makes every environment that installs a different upstream revision unresolvable.

Development

python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/ruff check .
.venv/bin/ruff format --check .
.venv/bin/mypy --config-file ../mypy.ini src
.venv/bin/pytest -m "not integration"

See the repository README and CONTRIBUTING.md.

License

Apache-2.0.