FlagQuantum MCP Servers

A collection of Model Context Protocol servers that give AI assistants, agents and IDEs direct access to the FlagQuantum SDK through a standardized protocol that works with any MCP-compatible client.

The reference design is Qiskit/mcp-servers, and we follow its packaging, testing and publishing conventions so that anyone who has configured a Qiskit MCP server already knows how to configure ours.

Servers

Quick start

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

Any MCP-compatible client works the same way, because there is no credential to configure:

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

See flagquantum-mcp-server/README.md for the full tool list and the limits each tool enforces, and flagquantum-mcp-server/examples/ for a runnable end-to-end script.

Running main instead of the latest release

Releases are batched deliberately, so main is regularly ahead of PyPI. To run the current main — a fix that has not been released yet, or a change under review — point the client at the repository instead of the package:

claude mcp add flagquantum -- uvx --from "git+https://github.com/FlagQuantum/mcp-servers.git#subdirectory=flagquantum-mcp-server" flagquantum-mcp-server

uvx reports the commit it built, such as flagquantum-mcp-server @ git+https://...#subdirectory=...@e9197fb. Quote that commit in a bug report rather than a version number: a checkout of main reports the last released version while carrying commits that release does not have, so the version alone does not identify what you ran. See CONTRIBUTING.md for the release policy.

Layout

mcp-servers/
├── flagquantum-mcp-server/     # one standalone PyPI package per server
│   ├── src/flagquantum_mcp_server/
│   ├── tests/
│   ├── examples/
│   ├── pyproject.toml
│   ├── server.json             # MCP Registry manifest
│   └── README.md
├── ruff.toml                   # shared lint config, extended per package
├── mypy.ini                    # shared type config
├── AGENTS.md                   # rules for agents working in this repo
├── CONTRIBUTING.md
└── .github/workflows/

Design constraints

These are deliberate, and each one is a departure from the reference suite that a reader should understand rather than "fix".

This repository is out of tree, permanently. FlagQuantum'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. Its AGENTS.md says MCP, REST, CLI and notebook adapters "remain thin" while the domain stays vendor- and SDK-neutral. Keeping protocol gateways at the system edge, in their own repository, is what that contract asks for. A test in tests/test_api_contract.py asserts the coupling points one way only.

There is no root meta-package yet. The reference suite ships qiskit-mcp-servers, which installs a chosen subset through extras. That earns its keep when the servers are genuinely separable, which for Qiskit they are: a local circuit server needs no IBM account, a runtime server needs a token, a gym server drags in torch through a reinforcement-learning stack. FlagQuantum has one SDK, one IR and no heavyweight subsystems to split, so a meta-package would aggregate nothing. It can be added when a second server exists.

No server here submits hardware jobs. FlagQuantum's released 0.2.0 ships no remote-submission entry point, and QPU submission is a governed capability — preflight, approval, budget, evidence — that belongs to a control plane rather than to a local adapter any agent can call. Every tool in this repository runs locally, deterministically, with no credentials and no outbound request. A server may listen, so that a client which connects to servers rather than launching them can reach it; that is an inbound socket, not egress.

One dependency is unavoidable and it is heavy. flagquantum requires torch, so any package here pulls it. The reference suite's four core servers are all light, and its qiskit-docs-mcp-server does not depend on qiskit at all — there is no equivalent here, because every tool needs the SDK. On Linux x86_64 a bare pip install resolves torch to the CUDA wheel set; CI pins the CPU index URL. Expect the first uvx run to be slow.

Which contracts a server may use

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". Servers here may use both, in tiers, and must say which tier they rest on:

Anything else — flagquantum.core.*, planner internals, executor internals — is off limits. See AGENTS.md.

Development

python3 -m venv .venv
.venv/bin/python -m pip install -e "./flagquantum-mcp-server[dev]"

cd flagquantum-mcp-server
../.venv/bin/ruff check .
../.venv/bin/ruff format --check .
../.venv/bin/mypy --config-file ../mypy.ini src
../.venv/bin/pytest -m "not integration"
../.venv/bin/pytest -m integration

The first install pulls torch. On Linux, prefer the CPU wheel:

.venv/bin/python -m pip install torch --index-url https://download.pytorch.org/whl/cpu

Adding a server

See CONTRIBUTING.md. Read AGENTS.md first: the boundary rules there are not stylistic.

License

Apache-2.0. See LICENSE.