FlagQuantum MCP Server

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/testserviceboundaries.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/testapicontract.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.

Shortened. The full README is on GitHub.