Protein Design Server

This repository has two parts under two different licenses — see NOTICE for full attribution.

1. The MCP server (this directory, outside claude-skills/) — Apache-2.0, based on jasonkim8652/protein-design-mcp. Currently unmodified from upstream; installation below correctly points to the upstream project's own PyPI/Docker/GitHub since qFoldIT has not yet published an independent build.
2. claude-skills/ — MIT, originally authored by qFoldIT: 21 Claude Skills covering scientific simulation (VQE, protein folding, bio-mining, corrosion, plant growth...) and digital-twin engine adapters (Unreal, Unity, Unigine, Omniverse, Apple, Three.js). See claude-skills/README.md.

Actual current directory layout (server portion; run tree claude-skills/ separately for the skills side):

Protein-Design-MCP/
├── README.md
├── NOTICE                    ← licensing/attribution for both parts of this repo
├── LICENSE                   ← Apache-2.0 (governs everything EXCEPT claude-skills/)
├── pyproject.toml
├── docker-compose.yml
├── Dockerfile*
├── src/protein_design_mcp/
│   ├── server.py
│   ├── pipelines/            (alphafold2, boltz_runner, esmfold, openmm_runner,
│   │                          proteinmpnn, pyrosetta_runner, rfdiffusion)
│   ├── tools/                (19 MCP tools -- design, predict, score, analyze)
│   ├── resources/
│   └── utils/
├── tests/
└── claude-skills/            ← MIT license (own LICENSE file), see claude-skills/README.md

PyPI Docker Hub GHCR Smithery License

An MCP server that gives LLM agents access to computational protein design tools. Ask your LLM to design binders, generate de novo folds, predict structures, score interfaces, or relax with Rosetta — it calls the right tool automatically.

25 tools total, spanning generative design, structure prediction, physics-based scoring, analysis, bioactivity/QSAR prediction, and quantum-computing-assisted peptide folding. Built on RFdiffusion, ProteinMPNN, ESMFold, AlphaFold2, Boltz-2, PyRosetta, ESM2, OpenMM, ZairaChem, QuPepFold (CVaR-VQE), and a classical simulation inspired by QFold's quantum-walk Metropolis algorithm. 3D output from any of these -- or from external MCPs like BindCraft's bindcraft_mcp -- can be exported to OpenUSD (uag_exporter.py) for NVIDIA Omniverse / NanoVer VR / Unreal / Unity.

Distribution	Tools out-of-the-box	Extras
pip install "protein-design-mcp[gpu]"	13 core tools	[rosetta] (license required), [boltz] (isolated venv)
docker pull jeonghyeonkim8652/protein-design-mcp	13 core tools (GPU), 10 (CPU)	PyRosetta / Boltz not bundled (license + torch conflict)

The 6 non-bundled tools (rosetta_* x4, predict_*_boltz x2) install cleanly via pip extras — see Optional Tools.

claude-skills/ (qFoldIT's own work, MIT-licensed)

The claude-skills/ subdirectory is a self-contained Claude Code plugin — 20 skills spanning scientific simulation (VQE quantum chemistry, HP-lattice protein folding, bio-mining kinetics, pipeline corrosion, plant growth/NPK modeling, L-systems, plastic pyrolysis) and a Universal Assembly Graph (UAG) based digital-twin pipeline with adapters for Unreal, Unity, Unigine, OpenUSD/Omniverse, Apple RealityKit, and Three.js. It has its own LICENSE (MIT), README.md, CITATION.cff, and governance docs (CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md). To install just this plugin in Claude Code, point a marketplace add at the claude-skills/ directory rather than the repo root. Full details: claude-skills/README.md.

---

MCP Server (upstream: jasonkim8652/protein-design-mcp, Apache-2.0)

Installation

Choose the method that fits your situation. Listed from simplest to most customizable.

---

1. Auto-Setup (Recommended)

One command. Detects your environment, pulls Docker if available, writes MCP client config.

pip install protein-design-mcp
protein-design-mcp-setup

What it does:

• Checks for Docker and NVIDIA GPU
• Pulls the Docker image (or falls back to local Python mode)
• Writes config for Claude Desktop or Claude Code automatically
• Model weights download lazily on first tool call

Options:

protein-design-mcp-setup --docker    # Force Docker mode
protein-design-mcp-setup --local     # Force local Python mode
protein-design-mcp-setup --modal URL # Use Modal cloud GPU
protein-design-mcp-setup -y          # Skip confirmation prompt

---

2. Smithery

If you use Smithery:

npx -y @smithery/cli install protein-design-mcp --client claude

---

3. pip + Manual Config

pip install protein-design-mcp                      # Core CPU (12 tools -- includes predict_structure_quantum_walk and export_structure_to_spatial_twin, no extra deps)
pip install "protein-design-mcp[gpu]"               # + PyTorch + ESM (15 tools)
pip install "protein-design-mcp[gpu,rosetta]"       # + PyRosetta (19 tools) *
pip install "protein-design-mcp[gpu,rosetta,boltz]" # + Boltz-2 (21 of 25 tools -- ZairaChem's 3 tools and predict_peptide_quantum_vqe need separate envs, see below) **

* PyRosetta requires a free academic license. The [rosetta] extra installs pyrosetta-installer which fetches the wheel after you accept the license.

** Boltz needs torch>=2.2 which conflicts with RFdiffusion's torch==2.0.1. Install in an isolated venv, not alongside [gpu].

Add to your MCP client config:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "protein-design": {
      "command": "protein-design-mcp"
    }
  }
}

Claude Code (.mcp.json in your project root):

{
  "mcpServers": {
    "protein-design": {
      "command": "protein-design-mcp"
    }
  }
}

Restart your client after editing config.

---

4. Docker

Isolated, reproducible environments with all computational backends pre-installed. Primary registry: Docker Hub.

Pull

# Latest release (GPU image, ~12GB, bundles RFdiffusion + ProteinMPNN + ESMFold + ColabFold + ESM2 + OpenMM)
docker pull jeonghyeonkim8652/protein-design-mcp:latest
docker pull jeonghyeonkim8652/protein-design-mcp:1.0.0   # pin a specific version

GHCR mirror (equivalent):

docker pull ghcr.io/jasonkim8652/protein-design-mcp:latest

Tools included in the image: 13 of 19. The 6 license/conflict-gated tools (rosetta_*, predict_*_boltz) are not bundled — install via pip extras instead. See Optional Tools.

Run (GPU)

Model weights download lazily on first use and persist in a named volume so subsequent runs are instant:

docker volume create protein-design-models

docker run --rm -i \
  --gpus all \
  -v protein-design-models:/models \
  -v $(pwd):/data \
  jeonghyeonkim8652/protein-design-mcp:latest

GPU mode requires NVIDIA Container Toolkit. The image stdin/stdout is the MCP protocol — you normally don't run it directly, your MCP client does (see below).

Run (CPU)

No GPU — works with the same image:

docker run --rm -i \
  -e DEVICE=cpu \
  -v protein-design-models:/models \
  -v $(pwd):/data \
  jeonghyeonkim8652/protein-design-mcp:latest

CPU mode disables design_binder, design_fold, generate_backbone (RFdiffusion is GPU-only) → 12 tools available.

MCP client config

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%/Claude/claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "protein-design": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--gpus", "all",
        "-e", "SKIP_MODEL_DOWNLOAD=true",
        "-v", "protein-design-models:/models",
        "-v", "/absolute/path/to/your/pdbs:/data",
        "jeonghyeonkim8652/protein-design-mcp:latest"
      ]
    }
  }
}

Claude Code (.mcp.json in your project root):

{
  "mcpServers": {
    "protein-design": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--gpus", "all",
        "-v", "protein-design-models:/models",
        "-v", "${workspaceFolder}:/data",
        "jeonghyeonkim8652/protein-design-mcp:latest"
      ]
    }
  }
}

For CPU-only hosts, drop "--gpus", "all" and add "-e", "DEVICE=cpu".

Restart your MCP client after editing config.

Tags available on Docker Hub

Tag	Purpose
latest	Tracks the most recent release on main
1.0.0, 1.0, 1	Semver-pinned (recommended for production)
<sha>	Exact commit SHA (immutable)

Check the full tag list at hub.docker.com/r/jeonghyeonkim8652/protein-design-mcp/tags.

Build locally

git clone https://github.com/jasonkim8652/protein-design-mcp.git
cd protein-design-mcp
docker build -t protein-design-mcp:dev .                  # GPU image
docker build -f Dockerfile.lite -t protein-design-mcp:lite .  # CPU-only, ~3-5GB

The GPU build needs ~30 GB free disk and ~20 minutes.

---

5. Modal (Cloud GPU)

No local GPU? Deploy to your own Modal account. Serverless GPU on demand, billed per-second (~$1.10/hr A10G). Containers auto-stop after 5 min idle.

pip install modal
modal setup                          # One-time: link your Modal account

git clone https://github.com/jasonkim8652/protein-design-mcp.git
cd protein-design-mcp
pip install -e .
modal deploy deploy/modal_app.py     # Deploy GPU endpoint

After deploying, Modal prints your endpoint URL. Connect via the local proxy:

{
  "mcpServers": {
    "protein-design": {
      "command": "python",
      "args": ["-m", "protein_design_mcp.modal_proxy"],
      "env": {
        "MODAL_URL": "https://<your-workspace>--protein-design-tools.modal.run"
      }
    }
  }
}

21 of 25 tools available (ZairaChem's 3 tools and predict_peptide_quantum_vqe need their own separate environments, see below -- not part of this Modal image). Local PDB files are automatically sent to Modal.

---

6. From Source (Development)

git clone https://github.com/jasonkim8652/protein-design-mcp.git
cd protein-design-mcp
pip install -e ".[gpu,dev]"
python -m protein_design_mcp.server

For full GPU pipeline, install RFdiffusion and ProteinMPNN separately and set RFDIFFUSION_PATH / PROTEINMPNN_PATH.

---

CPU vs GPU

	GPU	CPU
Tools available	All 19	14 (no design_binder, design_fold, generate_backbone, predict_structure_boltz, predict_affinity_boltz)
RFdiffusion	~30s/design	Disabled
Boltz-2	~10-30s	Disabled
ESMFold	~10s	~2-5min
ESM2	~5s	~30s
ProteinMPNN	~30s	~5-10min
PyRosetta	Fast	Comparable
OpenMM	Fast	Comparable
AlphaFold2 (API)	Works	Works

GPU is auto-detected. To force CPU mode, set DEVICE=cpu.

Available Tools

Tools marked (optional) are not bundled in the Docker image. See Optional Tools for install.

Design & Generation

design_binder (GPU only)

End-to-end binder design: RFdiffusion (backbone) -> ProteinMPNN (sequence) -> ESMFold (validation).

{
  "target_pdb": "path/to/target.pdb",
  "hotspot_residues": ["A45", "A46", "A49"],
  "num_designs": 10,
  "binder_length": 80
}

Returns ranked designs with sequences, PDB structures, pLDDT, pTM, and mpnn_score.

generate_backbone (GPU only)

De novo backbone generation using unconditional RFdiffusion. No target protein required.

{"length": 100, "num_designs": 5}

design_fold (GPU only)

End-to-end de novo fold design: RFdiffusion (unconditional backbone) → ProteinMPNN (sequence) → AlphaFold2 (validation, falls back to ESMFold). Returns ranked designs filtered by pLDDT/pTM.

{"length": 120, "num_designs": 10, "num_sequences_per_backbone": 4}

design_sequence

Design sequences for a given backbone using ProteinMPNN. Unlike optimize_sequence (which refines an existing sequence), this designs from scratch given only a backbone PDB — the correct tool after generate_backbone. Optionally validates each design with ESMFold.

{
  "backbone_pdb": "path/to/backbone.pdb",
  "num_sequences": 8,
  "sampling_temp": 0.1,
  "fixed_positions": [1, 5, 10],
  "validate": true
}

optimize_sequence

Redesign a protein sequence for improved stability and/or binding affinity using ProteinMPNN.

{
  "current_sequence": "MTKLYV...",
  "target_pdb": "path/to/target.pdb",
  "optimization_target": "both",
  "fixed_positions": [1, 5, 10]
}

Structure Prediction

predict_structure

Single-chain structure prediction via ESMFold (fast) or AlphaFold2 (accurate).

{"sequence": "MTKLYV...", "predictor": "esmfold"}

Returns PDB file, mean pLDDT, pTM, per-residue confidence.

predict_complex

Multi-chain complex structure prediction using AlphaFold2-Multimer.

{
  "sequences": ["BINDER_SEQ...", "TARGET_SEQ..."],
  "chain_names": ["binder", "target"]
}

Returns predicted complex PDB with pLDDT, pTM/ipTM, and PAE matrix.

predict_structure_boltz (GPU only, optional)

Single-chain structure prediction with Boltz-2 — a fast, high-accuracy open model competitive with AF2.

{"sequence": "MTKLYV...", "model": "boltz2", "num_samples": 1}

Returns predicted PDB, mean pLDDT, pTM.

predict_affinity_boltz (GPU only, optional)

Multi-chain complex + binding affinity prediction with Boltz-2. Returns affinity score alongside the predicted complex structure and confidence metrics.

{"sequences": ["BINDER_SEQ...", "TARGET_SEQ..."], "model": "boltz2"}

validate_design

Predict structure of a designed sequence and optionally compute RMSD against a reference.

{
  "sequence": "MTKLYV...",
  "expected_structure": "path/to/reference.pdb",
  "predictor": "esmfold"
}

Analysis & Scoring

analyze_interface

Analyze protein-protein interface: contacts, buried surface area, hydrogen bonds, salt bridges.

{"complex_pdb": "path/to/complex.pdb", "chain_a": "A", "chain_b": "B"}

suggest_hotspots

Predict binding hotspots from multiple sources. Accepts protein names, UniProt IDs, PDB IDs, or file paths.

{"target": "EGFR", "criteria": "druggable", "include_literature": true}

Criteria: "exposed" (SASA), "druggable" (pocket geometry), "conserved" (evolution).

score_stability

Protein stability scoring via ESM2 pseudo-log-likelihood. Optionally score individual mutations.

{
  "sequence": "MTKLYV...",
  "mutations": ["A42G", "L55V"]
}

Returns overall stability score and per-mutation delta log-likelihood (stabilizing/destabilizing).

energy_minimize

All-atom energy minimization with OpenMM (AMBER14 + implicit solvent).

{"pdb_path": "path/to/structure.pdb", "num_steps": 500, "solvent": "implicit"}

Returns minimized PDB, energy change, and RMSD from input.

Rosetta (Physics-Based Design & Scoring) — optional

PyRosetta-backed tools for physics-based scoring, relaxation, and fixed-backbone design. All use ref2015 by default. Not bundled in Docker — install via pip install "protein-design-mcp[rosetta]" after accepting the PyRosetta license.

rosetta_score

Score a structure with a Rosetta energy function. Returns total score, per-residue energies, and component breakdown.

{"pdb_path": "path/to/structure.pdb", "score_function": "ref2015"}

rosetta_relax

FastRelax protocol to find a low-energy conformation. Returns relaxed PDB, energy before/after, and CA-RMSD from input.

{"pdb_path": "path/to/structure.pdb", "nstruct": 1}

rosetta_interface_score

Interface analysis via InterfaceAnalyzerMover: binding energy (dG_separated), buried surface area (dSASA), interface hydrogen bonds, packstat.

{"pdb_path": "path/to/complex.pdb", "chains": "A_B"}

rosetta_design

Fixed-backbone redesign pipeline: score → PackRotamers → MinMover → score. Returns designed PDB, mutation list, and energy delta. Composite tool — in benchmark mode, call rosetta_score / rosetta_relax individually instead.

{"pdb_path": "path/to/input.pdb", "chains": "A_B", "fixed_positions": [12, 14, 18]}

Bioactivity / QSAR (optional, see Optional Tools: ZairaChem)

predict_bioactivity (optional)

Score candidate molecules against a trained ZairaChem model (yours, or a published pretrained one e.g. from the H3D Centre screening cascade). Classification only.

{"input_csv": "path/to/candidates.csv", "model_dir": "path/to/model", "output_dir": "path/to/output"}

train_qsar_model (optional)

Train a new binary-classification QSAR model from labeled SMILES + activity data.

{"input_csv": "path/to/training_data.csv", "output_dir": "path/to/model_output", "cutoff": 6.5, "direction": "high"}

predict_admet_profile (optional)

Run ZairaChem's predict across every endpoint you've configured (solubility, toxicity, malaria/tuberculosis bioactivity via ZAIRACHEM_MODEL_<ENDPOINT> env vars, e.g. from the H3D Centre screening cascade) for a single SMILES, and return one combined profile. Endpoints with no configured model report "status": "not_configured" rather than a fabricated score.

{"smiles": "CCO"}

Quantum Peptide Folding & Spatial Digital Twin (optional, see Optional Tools: QuPepFold)

predict_peptide_quantum_vqe (optional)

Estimate a low-energy peptide conformation with QuPepFold's CVaR-optimized Variational Quantum Eigensolver (Qiskit Aer / Amazon Braket / IonQ Aria-1). Best suited to short peptides (≲10 residues). If qupepfold isn't installed in the active environment, returns a structured "status": "unavailable" result instead of failing.

{"sequence": "ACDEFGHIK", "alpha": 0.1, "shots": 1024}

predict_structure_quantum_walk

Classical, quantum-walk-inspired torsion-angle (φ,ψ) Metropolis simulation, loosely modeled on QFold's continuous off-lattice algorithm, followed by NeRF backbone reconstruction. Returns a 3D N/CA/C coordinate tensor. Pure Python — no extra dependency, available in every install including core CPU.

{"sequence": "ACDEFGHIK", "steps": 500, "continuous_space": true}

Feed the resulting coordinates (or Boltz-2's output, reshaped similarly) into uag_exporter.export_to_openusd() to get a .usda file for NVIDIA Omniverse, NanoVer VR, Unreal Engine 5, or Unity. Uses real pxr/UsdGeom if usd-core is installed (pip install "protein-design-mcp[usd]"); otherwise falls back to a hand-written, schema-valid ASCII .usda writer with no extra dependency.

Utility

get_design_status

Check progress of long-running design jobs.

{"job_id": "abc123"}

export_structure_to_spatial_twin

Export any existing PDB file to OpenUSD (.usda), for NVIDIA Omniverse / NanoVer VR / Unreal Engine 5 / Unity. Source-agnostic -- works on this server's own PDB output as well as PDB output from external MCPs (see Optional Tools: MacromNex/BindCraft).

{"pdb_path": "path/to/structure.pdb", "output_path": "path/to/output.usda"}

Optional Tools: PyRosetta + Boltz-2

These 6 tools (rosetta_score, rosetta_relax, rosetta_interface_score, rosetta_design, predict_structure_boltz, predict_affinity_boltz) are not included in the Docker image because:

• PyRosetta requires a Rosetta license (free for academics, paid for commercial) and cannot be legally redistributed in a container.
• Boltz-2 needs torch>=2.2, while RFdiffusion's dependency chain (e3nn, dgl) pins torch==2.0.1. Both cannot coexist in one venv.

Installing PyRosetta tools

1. Register at pyrosetta.org/downloads and accept the license.
2. Install alongside the MCP server:

   pip install "protein-design-mcp[gpu,rosetta]"
   python -c "import pyrosetta_installer; pyrosetta_installer.install_pyrosetta()"
   

3. Verify: python -c "import pyrosetta; print(pyrosetta.__version__)"

The 4 rosetta_* tools become available immediately.

Installing Boltz-2 tools

Create a separate virtualenv (isolated from the RFdiffusion torch stack):

python -m venv ~/.venvs/protein-design-boltz
source ~/.venvs/protein-design-boltz/bin/activate
pip install "protein-design-mcp[boltz]"

Then point your MCP client at this venv's protein-design-mcp binary (or run two MCP servers — one for RFdiffusion/Docker tools, one for Boltz).

Configuring two MCP servers side-by-side

{
  "mcpServers": {
    "protein-design": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--gpus", "all",
               "-v", "protein-design-models:/models",
               "jeonghyeonkim8652/protein-design-mcp:latest"]
    },
    "protein-design-boltz": {
      "command": "/home/you/.venvs/protein-design-boltz/bin/protein-design-mcp"
    }
  }
}

Your LLM will see all 20 of those tools through the two servers (includes predict_structure_quantum_walk, which needs no extra dependency) and call whichever is appropriate (add a third server entry pointing at a zairachem conda env's Python for the 3 ZairaChem tools, and a fourth pointing at a quantum venv for predict_peptide_quantum_vqe, following the same pattern -- see claude_desktop_config.json in the repo root for a complete 4-server example).

Optional Tools: ZairaChem (bioactivity/QSAR prediction)

predict_bioactivity, train_qsar_model, and predict_admet_profile wrap ZairaChem, a published open-source AutoML QSAR/QSPR pipeline from the Ersilia Open Source Initiative (Turon, Hlozek, Woodland et al., "First fully-automated AI/ML virtual screening cascade implemented at a drug discovery centre in Africa," Nature Communications 14, 5736, 2023). ZairaChem was co-developed with and validated at the H3D Centre (University of Cape Town) -- pretrained models from that malaria/tuberculosis screening cascade are published separately at ersilia-os/h3d-screening-cascade-models and can be used directly with predict_bioactivity/predict_admet_profile with no retraining needed.

Not included in the Docker image for the same class of reason as PyRosetta/Boltz-2: ZairaChem is a heavy, conda-orchestrated, multi-environment AutoML stack (it also depends on the separately-installed Ersilia Model Hub CLI for descriptor calculation, which itself needs Docker or Singularity for most descriptor models) -- not something that fits cleanly into a single pip extra or a shared container alongside RFdiffusion's pinned torch stack.

Installing ZairaChem

git clone https://github.com/ersilia-os/zaira-chem.git
cd zaira-chem
bash install_script.sh
conda activate zairachem

Verify: zairachem --help should print the CLI's subcommands (fit, predict, distill).

Then point a separate MCP server instance at this conda environment's Python (same "configure two/three MCP servers side-by-side" pattern shown above for Boltz-2).

Usage notes

• Classification only (not regression) -- binarize continuous assay data yourself, or pass cutoff/direction to train_qsar_model and let ZairaChem do it.
• predict_bioactivity needs an existing model -- either one you trained with train_qsar_model, or a pretrained one (e.g. download an H3D screening-cascade model for a malaria/TB-relevant endpoint and point model_dir at it directly).
• Natural pipeline position: score candidate molecules from design_binder/design_fold/an external molecule-generation step (e.g. qFoldIT's genmol skill) for predicted bioactivity before committing to expensive downstream validation (docking, synthesis).
• Descriptor calculation (especially GROVER embeddings) can be slow on first run or CPU-only setups -- both new tools default to a generous 4-hour subprocess timeout, configurable via ZairaChemConfig.timeout_seconds in pipelines/zairachem_runner.py.

Optional Tools: QuPepFold (quantum peptide folding)

predict_peptide_quantum_vqe wraps QuPepFold, a published Python package for CVaR-tuned Variational Quantum Eigensolver peptide conformational sampling (Uttarkar, Niranjan, Saxena, Kumar, "QuPepFold: A python package for hybrid quantum-classical protein folding simulations with CVaR-optimized VQE," PLOS ONE, 2026, doi:10.1371/journal.pone.0342012), runnable on Qiskit Aer, Amazon Braket's tensor-network simulator, or IonQ Aria-1 hardware. No official package repository URL was independently verified for this addition -- install from PyPI (pip install qupepfold) if available, or from the paper's own supplementary materials/links, and confirm the source before pinning a version in production.

Not included in any bundled image for the same class of reason as PyRosetta/Boltz-2: Qiskit + Amazon Braket SDK + qupepfold is a large, independent dependency stack best kept in its own venv.

Installing the quantum stack

python -m venv ~/.venvs/protein-design-quantum
source ~/.venvs/protein-design-quantum/bin/activate
pip install "protein-design-mcp[quantum]"

Then point a separate MCP server instance at this venv's Python -- see claude_desktop_config.json in the repo root for a worked 5-environment example (core / boltz / zairachem / quantum / macromnex-bindcraft), or the "Configuring two MCP servers side-by-side" pattern above.

Usage notes

• Best suited to short peptides (≲10 residues) -- matches the published benchmark range where CVaR-VQE reliably reaches the ground state.
• Never crashes the server if unavailable: if qupepfold isn't importable, predict_peptide_quantum_vqe returns {"status": "unavailable", "install_hint": ...} instead of raising.
• predict_structure_quantum_walk (the classical, quantum-walk-inspired Metropolis simulation + NeRF backbone builder) needs no extra dependency and is available in every install, including the base pip install protein-design-mcp. See pipelines/quantum_runner.py's module docstring for exactly what it does and doesn't reproduce from the real QFold quantum-walk algorithm.
• QuPepFold's exact importable Python API (class/function names) was not independently re-verified against an installed copy of the package when this wrapper was written -- see _run_qupepfold_job in pipelines/quantum_runner.py before relying on it in production.

Spatial Digital Twin Export (OpenUSD)

uag_exporter.export_to_openusd(atom_coordinates, output_path) converts any 3D atom-coordinate list produced by this server (Boltz-2, predict_structure_quantum_walk, RFdiffusion, etc. -- anything shaped as a list of {atom, element, x, y, z, residue_index} dicts) into a .usda OpenUSD scene, for live sync with NVIDIA Omniverse, NanoVer VR, Unreal Engine 5, or Unity.

pip install "protein-design-mcp[usd]"   # optional -- enables the real pxr/UsdGeom path

Without usd-core installed, the same function still works via a hand-written, schema-valid ASCII .usda fallback (no extra dependency) -- you lose time-sampling/composition-arc support, but get a working file either way.

export_structure_to_spatial_twin -- exporting any PDB file, including from external MCPs

For anything that only produces a PDB file rather than this repo's own coordinate-dict shape, use the export_structure_to_spatial_twin MCP tool (or uag_exporter.export_pdb_to_openusd(pdb_path, output_path) directly): it parses the PDB with this repo's own utils/pdb.py, flattens it to the coordinate-dict shape above, and hands it straight to export_to_openusd. It has no dependency on whatever tool produced the PDB -- it only reads a file path off disk.

{"pdb_path": "path/to/binder_design.pdb", "output_path": "path/to/output.usda"}

This is the integration point for BindCraft (via ProteinMCP's bindcraft_mcp, see Optional Tools: MacromNex/BindCraft below) -- point this tool at whatever .pdb file BindCraft's quick_design writes to disk and get back a live OpenUSD 3D model, no manual conversion step required.

Optional Tools: MacromNex/BindCraft (binder design)

claude_desktop_config.json's 5th server entry, qfoldit-mcp-macromnex-bindcraft, launches an external, independently-maintained MCP: bindcraft_mcp, a wrapper around BindCraft (Pacesa, Nickel, Schellhaas et al., "One-shot design of functional protein binders with BindCraft," developed at EPFL's Correia Lab with MIT's Ovchinnikov Lab). bindcraft_mcp itself is published as part of ProteinMCP (Xu et al., Protein Science, 2026, doi:10.1002/pro.70547), forked at MacromNex/ProteinMCP -- MacromNex is a real, independently-confirmed GitHub organization ("Macromolecular Nexus") focused on macromolecular design tooling.

Naming note: "macromnex-bindcraft" is this config entry's own label, not a published package or command name -- no repository by that exact name was found. What actually gets launched is bindcraft_mcp's own src/server.py, run with its own dedicated conda/mamba environment's Python (its documented invocation is <env>/bin/python src/server.py, using fastmcp) -- not this repo's protein_design_mcp.server module. See the config entry's own inline comment for the full correction.

Not vendored in this repo -- it's a separate project with its own install script, its own JAX/CUDA setup, and its own PyRosetta license requirement (same license terms as this repo's own rosetta_* tools). To use it:

1. Clone MacromNex/ProteinMCP (or charlesxu90/ProteinMCP) and follow tool-mcps/bindcraft_mcp's own README for environment setup (creates its own ./env, installs BindCraft itself).
2. Point claude_desktop_config.json's qfoldit-mcp-macromnex-bindcraft entry's paths at wherever that ends up on your machine.
3. Once it's running, its quick_design (or async equivalent) tool writes a .pdb file -- feed that path directly to this repo's own export_structure_to_spatial_twin tool to get a live OpenUSD 3D model in Omniverse/NanoVer/Unreal/Unity.

One framing note: MacromNex's own stated mission (per its GitHub organization page) is "Geometric Deep Learning, Molecular Physics, and Synthetic Biology" research -- it does not describe itself as a gamification or gaming initiative anywhere in its own materials. Any "gamification"/game-related framing applied to this integration is qFoldIT's own product positioning, not a claim made by or about MacromNex, BindCraft, or ProteinMCP.

Configuration

Variable	Description	Default
DEVICE	"auto", "cuda", or "cpu"	auto
RFDIFFUSION_PATH	Path to RFdiffusion installation	/opt/RFdiffusion
PROTEINMPNN_PATH	Path to ProteinMPNN installation	/opt/ProteinMPNN
COLABFOLD_BACKEND	"api" (remote MSA) or "local" (local DB)	api
CACHE_DIR	Cache directory	~/.cache/protein-design-mcp
TORCH_HOME	ESM model weights directory	(PyTorch default)
SKIP_MODEL_DOWNLOAD	Skip eager weight download in Docker	true

Architecture

MCP Server (stdio)
 |
 +-- Design tools
 |    +-- design_binder         RFdiffusion -> ProteinMPNN -> ESMFold
 |    +-- design_fold           RFdiffusion -> ProteinMPNN -> AlphaFold2
 |    +-- generate_backbone     RFdiffusion (unconditional)
 |    +-- design_sequence       ProteinMPNN (+ optional ESMFold validation)
 |    +-- optimize_sequence     ProteinMPNN + ESMFold
 |
 +-- Structure prediction
 |    +-- predict_structure       ESMFold or AlphaFold2
 |    +-- predict_complex         AlphaFold2-Multimer (ColabFold)
 |    +-- predict_structure_boltz Boltz-2 (monomer)
 |    +-- predict_affinity_boltz  Boltz-2 (complex + affinity)
 |    +-- validate_design         Structure prediction + RMSD
 |
 +-- Rosetta (PyRosetta)
 |    +-- rosetta_score           ref2015 energy scoring
 |    +-- rosetta_relax           FastRelax
 |    +-- rosetta_interface_score InterfaceAnalyzerMover
 |    +-- rosetta_design          PackRotamers + MinMover
 |
 +-- Bioactivity / QSAR (ZairaChem)
 |    +-- predict_bioactivity     Score molecules against a trained/pretrained model
 |    +-- train_qsar_model        Train a new binary-classification QSAR model
 |    +-- predict_admet_profile   Multi-endpoint ZairaChem orchestration (solubility/toxicity/bioactivity)
 |
 +-- Quantum peptide folding
 |    +-- predict_peptide_quantum_vqe     QuPepFold CVaR-VQE (Qiskit/Braket)
 |    +-- predict_structure_quantum_walk  Classical quantum-walk-inspired Metropolis + NeRF
 |
 +-- Spatial digital twin export
 |    +-- uag_exporter.export_to_openusd      Atom coordinates -> OpenUSD (.usda)
 |    +-- export_structure_to_spatial_twin    Any PDB file -> OpenUSD (source-agnostic, incl. external MCPs)
 |
 +-- Analysis tools
 |    +-- analyze_interface   PDB geometry analysis
 |    +-- suggest_hotspots    SASA + pockets + UniProt + PubMed
 |    +-- score_stability     ESM2 pseudo-log-likelihood
 |    +-- energy_minimize     OpenMM (AMBER14)
 |
 +-- Utilities
      +-- get_design_status  Job queue polling
      +-- Structure fetching (RCSB, AlphaFold DB, UniProt)
      +-- Conservation scoring, caching

Development

git clone https://github.com/jasonkim8652/protein-design-mcp.git
cd protein-design-mcp
pip install -e ".[gpu,dev]"

pytest tests/           # Run tests
ruff check .            # Lint
black .                 # Format
mypy src/               # Type check

License

Apache License 2.0 - see LICENSE for details.

References

• MCP Specification
• RFdiffusion - Protein backbone generation
• ProteinMPNN - Sequence design
• ESMFold / ESM2 - Structure prediction and stability scoring
• ColabFold - Fast AlphaFold2 with MMseqs2
• Boltz - Open structure and affinity prediction
• PyRosetta - Physics-based protein modeling
• OpenMM - Molecular dynamics and energy minimization
• ZairaChem - AutoML QSAR/bioactivity prediction (Turon, Hlozek, Woodland et al., "First fully-automated AI/ML virtual screening cascade implemented at a drug discovery centre in Africa," Nature Communications 14, 5736, 2023, https://doi.org/10.1038/s41467-023-41512-2)
• H3D Centre screening cascade models - Pretrained ZairaChem models usable directly with predict_bioactivity / predict_admet_profile
• QuPepFold - CVaR-optimized VQE peptide folding (Uttarkar, Niranjan, Saxena, Kumar, PLOS ONE, 2026, https://doi.org/10.1371/journal.pone.0342012)
• QFold - Quantum-walk Metropolis protein folding (Casares, Campos, Martin-Delgado, "QFold: quantum walks and deep learning to solve protein folding," Quantum Science and Technology 7, 025013, 2022, https://doi.org/10.1088/2058-9565/ac4f2f, arXiv:2101.10279) -- classical inspiration only for predict_structure_quantum_walk, see that tool's own scope note
• OpenUSD - Scene description format used by uag_exporter.py for spatial digital-twin export (NVIDIA Omniverse, NanoVer VR, Unreal Engine 5, Unity)
• BindCraft - De novo protein binder design (Pacesa, Nickel, Schellhaas et al., EPFL Correia Lab / MIT Ovchinnikov Lab). Not vendored -- integrated externally via bindcraft_mcp, see Optional Tools: MacromNex/BindCraft
• ProteinMCP - Agentic MCP framework packaging BindCraft as bindcraft_mcp (Xu et al., Protein Science, 2026, https://doi.org/10.1002/pro.70547), forked at MacromNex/ProteinMCP
• Full citation metadata, including software/consortium references: see CITATION.cff