SQuADDS MCP Server

Model Context Protocol (MCP) server for the SQuADDS superconducting quantum device design database.

This MCP server wraps the SQuADDS Python library, making the database of pre-simulated superconducting quantum device designs accessible to AI agents (Claude, Cursor, VS Code Copilot, Gemini, Codex, and custom LLM agents) and human developers through the standardized Model Context Protocol.

Agent Setup (Copy-Paste This to Your AI Agent)

If you're using an AI coding assistant, just paste this prompt into it to have it set up everything for you:

I need you to set up the SQuADDS MCP server so I can access the superconducting
qubit design database through you. Here's what to do:

1. Clone the repo and install:
   git clone https://github.com/LFL-Lab/SQuADDS.git
   cd SQuADDS
   uv sync --extra mcp

2. Add the MCP server to your config. The command to run the server is:
   uv run --directory /path/to/SQuADDS squadds-mcp

3. Once connected, read the `squadds://guide` resource for a quick overview
   of available tools.

The server exposes these key tools:
- `list_components` / `list_datasets` — explore the database
- `find_closest_designs` — find designs matching target Hamiltonian parameters
- `interpolate_design` — get physics-interpolated designs
- `get_hamiltonian_param_keys` — discover valid search parameters

Typical target parameter ranges:
- qubit_frequency_GHz: 3–8
- anharmonicity_MHz: −500 to −50
- cavity_frequency_GHz: 5–12
- kappa_kHz: 10–1000
- g_MHz: 10–200

Please set this up and confirm you can access the SQuADDS tools.

Manual Setup

1. Install dependencies

cd SQuADDS
uv sync --extra mcp

2. Set up HuggingFace authentication

# Option A: environment variable
export HF_TOKEN=your_token_here

# Option B: huggingface CLI login
uv run huggingface-cli login

3. Run the server

# Run via the CLI entrypoint (stdio mode — for local AI assistants)
uv run squadds-mcp

# Or run the module directly
uv run python -m squadds_mcp.server

# HTTP mode (for networked/remote usage)
SQUADDS_MCP_TRANSPORT=streamable-http SQUADDS_MCP_PORT=8000 uv run squadds-mcp

4. Connect from an AI client

{
  "mcpServers": {
    "squadds": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/SQuADDS", "squadds-mcp"],
      "env": {
        "HF_TOKEN": "your_token_here"
      }
    }
  }
}

claude mcp add squadds -- uv run --directory /path/to/SQuADDS squadds-mcp

{
  "mcpServers": {
    "squadds": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/SQuADDS", "squadds-mcp"]
    }
  }
}

{
  "mcp": {
    "servers": {
      "squadds": {
        "command": "uv",
        "args": ["run", "--directory", "/path/to/SQuADDS", "squadds-mcp"]
      }
    }
  }
}

{
  "mcpServers": {
    "squadds": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/SQuADDS", "squadds-mcp"]
    }
  }
}

{
  "mcpServers": {
    "squadds": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/SQuADDS", "squadds-mcp"]
    }
  }
}

codex --mcp-config mcp.json

{
  "mcpServers": {
    "squadds": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/SQuADDS", "squadds-mcp"]
    }
  }
}

SQUADDS_MCP_TRANSPORT=streamable-http SQUADDS_MCP_PORT=8000 uv run squadds-mcp

Architecture

┌─────────────┐
│  AI Client   │  Claude Desktop, Cursor, Custom Agent
└──────┬──────┘
       │ MCP Protocol (stdio or HTTP)
┌──────▼──────────────────────────────┐
│         SQuADDS MCP Server          │
│  ┌────────┐ ┌──────────┐ ┌───────┐ │
│  │ Tools  │ │Resources │ │Prompts│ │
│  └────┬───┘ └────┬─────┘ └───┬───┘ │
│       │          │            │     │
│  ┌────▼──────────▼────────────▼───┐ │
│  │        SQuADDS Library         │ │
│  │  (SQuADDS_DB, Analyzer, etc.)  │ │
│  └──────────────┬─────────────────┘ │
└─────────────────┼───────────────────┘
                  │
         ┌────────▼────────┐
         │  HuggingFace Hub │
         │  (SQuADDS_DB)    │
         └─────────────────┘

Available Tools

Database Tools

Analysis Tools

Interpolation Tools

Contribution Tools

Available Resources

Available Prompts

Example: Finding a Qubit-Cavity Design

Here's what an AI agent interaction looks like:

User: Design a transmon qubit coupled to a quarter-wave resonator.
      Target: qubit at 4.5 GHz, anharmonicity -220 MHz,
      cavity at 9.0 GHz, kappa 100 kHz, coupling 75 MHz.

Agent: I'll search the SQuADDS database for matching designs.
       [calls find_closest_designs with target_params]

Agent: Found 3 matching designs. The closest has:
       - Qubit frequency: 4.48 GHz (target: 4.5)
       - Anharmonicity: -218 MHz (target: -220)
       - Cross length: 310 um
       - Claw length: 86 um
       - Resonator length: 4200 um
       ...

Environment Variables

Testing with MCP Inspector

# Start the server
uv run squadds-mcp &

# Connect with the Inspector
npx -y @modelcontextprotocol/inspector

Then connect to http://localhost:8000/mcp (if HTTP) or use stdio mode in the Inspector.

Project Structure

squadds_mcp/
├── __init__.py           # Package version
├── server.py             # FastMCP server, lifespan, CLI entrypoint
├── schemas.py            # Pydantic models for structured I/O
├── utils.py              # Serialization & formatting helpers
├── tools/
│   ├── database.py       # DB browsing & query tools
│   ├── analysis.py       # Design search tools
│   ├── interpolation.py  # Scaling interpolation tools
│   └── contribution.py   # Contributor & device info tools
├── resources/
│   └── metadata.py       # Read-only data resources
└── prompts/
    └── workflows.py      # Guided workflow prompts

Citation

If you use SQuADDS in your research, please cite:

@article{Shanto2024squaddsvalidated,
  doi = {10.22331/q-2024-09-09-1465},
  title = {{SQuADDS}: A validated design database and simulation workflow for superconducting qubit design},
  author = {Shanto, Sadman and Kuo, Andre and Miyamoto, Clark and Zhang, Haimeng and Maurya, Vivek and Vlachos, Evangelos and Hecht, Malida and Shum, Chung Wa and Levenson-Falk, Eli},
  journal = {Quantum},
  volume = {8},
  pages = {1465},
  year = {2024}
}