mcp-bionemo
This MCP server exposes typed protein-design operations for RFdiffusion, ProteinMPNN, and Boltz-2, using a deterministic simulator by default with optional live backend routing.
Discover the active backend and available tools via
info.Design a protein backbone with RFdiffusion via
design_backbone, using target PDB text, contigs, and optional hotspot residues.Design amino-acid sequences for a backbone with ProteinMPNN via
design_sequences, including configurable sequence count.Co-fold protein chains and optional small-molecule ligands with Boltz-2 via
fold_complex, optionally estimating binding affinity.Run a combined RFdiffusion + ProteinMPNN binder-design pipeline via
design_binder.Use the offline simulator without credentials, or route calls to configured live NIM endpoints via environment variables.
Provides tools for NVIDIA BioNeMo biology NIMs, including RFdiffusion for protein backbone design, ProteinMPNN for amino-acid sequence design, and Boltz-2 for co-folding protein chains and optional affinity estimates. It can run against a simulator by default or route to live BioNeMo NIM endpoints.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-bionemo design a binder against the SARS-CoV-2 spike protein and fold the complex"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-bionemo
Motivation
An agent using scientific models needs a clear contract for each tool’s inputs, outputs and errors. Connecting every client directly to endpoint-specific HTTP calls also makes integration difficult to test without credentials or model access.
Related MCP server: Enterprise MCP Gateway and Tool Registry
What the program does
mcp-bionemo exposes selected protein-design model operations (RFdiffusion, ProteinMPNN, Boltz-2) as typed Model Context Protocol (MCP) tools. An MCP client can discover the tools, submit structured requests and receive results through one interface. A deterministic simulator supports offline integration tests, while an optional live backend routes calls to configured NIM endpoints. The project focuses on the integration boundary, not scientific validation.
What this project demonstrates
Demonstrates a lightweight typed MCP interface for selected protein-design model endpoints and a deterministic integration simulator.
CLI example

Portfolio examples. Clinical recordings use the separate simplified interactive demo.
Try it offline
Python 3.11–3.13. In a fresh virtual environment, from this repository:
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
pytest -q
python examples/client_walkthrough.pyRun with a configured model backend
Install .[live]; set BIONEMO_BACKEND=live, NGC_API_KEY or NVIDIA_API_KEY, and optionally BIONEMO_BASE_URL. Use real scientific inputs. This wrapper focuses on typed MCP calls and offline integration.
Model IDs in .env.example and NAT configs are examples, not a current availability guarantee. Check your endpoint before running; the validation below does not include live model execution.
What is verified
Simulator tool contracts, stable seeds and mocked HTTP error/payload handling. Selected client interoperability is tested; universal MCP-client compatibility is not claimed.
Validation layer | Status |
Unit/regression tests | Executed locally on Python 3.12; see |
Mocked/simulated integrations | Executed locally; scope documented in tests |
Live hosted endpoints | Not executed; access and appropriate inputs required |
Self-hosted GPU endpoints | Not executed |
Domain-specific validation | Not completed; synthetic examples only |
See validation details. The architecture and detailed workflows follow.
Architecture and detailed workflows
A Model Context Protocol (MCP) server for protein-design models. It exposes RFdiffusion, ProteinMPNN and Boltz-2 as typed MCP tools, so compatible MCP clients (Claude Desktop, Cursor, an IDE agent or an agent framework's MCP client) can discover and call them like any other tool. It runs against a deterministic simulator by default, so you can install and explore it with no GPU, no key and no network.
Demo
The stdio MCP client discovers the available tools and invokes design_backbone against the simulator. The image shows the actual command and returned output. The command/output examples are on anhduongvo.github.io.
Background
Protein-design models are often served as HTTP endpoints. This repository supplies a lightweight typed MCP interface with an offline simulator. mcp-bionemo wraps the endpoints in MCP tools with typed input schemas. The same tools route to the real endpoints with one environment variable.
Quickstart
pip install -e .
# try it with the MCP inspector, or wire it into a client (below). No key needed: it runs the simulator.Point an MCP client at the server over stdio with the command mcp-bionemo. For Claude Desktop, add examples/claude_desktop_config.json to your config.
Tools
Tool | Model | What it does |
| RFdiffusion | Design a protein backbone against a target (contigs, optional hotspot residues) |
| ProteinMPNN | Design amino-acid sequences that fold to a backbone |
| Boltz-2 | Co-fold protein chains (and optional ligands), with an optional affinity estimate |
| RFdiffusion + ProteinMPNN | Backbone then sequences in one call |
| — | Report the active backend and the available tools |
Fold the binder together with the target to score binding; a binder folded alone does not measure binding. The tool docstrings say so.
Simulated vs live
By default the server uses an in-process simulator that returns well-formed but meaningless structures and scores: it exercises the tool contracts and the orchestration, not the biology. To call real hosted model endpoints, set:
BIONEMO_BACKEND=live
NGC_API_KEY=nvapi-xxxx # API key for the hosted endpoint
# or, for a self-hosted server:
BIONEMO_BASE_URL=https://your-host/v1Hosted endpoints return HTTP 202 for long jobs; the client polls the status endpoint until the result is ready.
Development
pip install -e ".[dev]"
ruff check .
pytest # exercises every tool against the simulatorLicense
Apache-2.0. This project calls NVIDIA BioNeMo NIMs but is not affiliated with or endorsed by NVIDIA.
Available Tools
5 toolsdesign_backboneB
Design a protein backbone with RFdiffusion.
Args: input_pdb: the target structure as PDB text (the scaffold/target to design against). contigs: RFdiffusion contig string describing what to generate, e.g. "A1-100/0 50-60". hotspot_res: optional target residues the binder should contact, e.g. ["A59", "A83"].
Returns a dict with output_pdb (the generated backbone as PDB text).
Inputs: contigs (required), input_pdb (required), hotspot_res. Returns: object
design_binderA
Convenience pipeline: RFdiffusion backbone, then ProteinMPNN sequences for it, in one call.
Returns a dict with backbone_pdb and designs (FASTA) plus scores. Fold the designs against
the target with fold_complex to score binding.
Inputs: contigs (required), target_pdb (required), hotspot_res, num_sequences. Returns: object
design_sequencesB
Design amino-acid sequences that fold to a given backbone with ProteinMPNN.
Args: input_pdb: the backbone (PDB text) to design sequences for. num_sequences: how many candidate sequences to return.
Returns a dict with mfasta (FASTA of designs) and scores (lower is better).
Inputs: input_pdb (required), num_sequences. Returns: object
fold_complexA
Co-fold one or more protein chains (optionally with small-molecule ligands) using Boltz-2.
Args: protein_sequences: one amino-acid sequence per protein chain. Give the binder AND the target together to score the complex; a binder folded alone does not measure binding. ligand_smiles: optional list of SMILES strings for small-molecule ligands. predict_affinity: if true and a ligand is given, also return a binding-affinity estimate.
Returns a dict with structures, confidence_scores, and (optionally) affinities.
Inputs: protein_sequences (required), ligand_smiles, predict_affinity. Returns: object
infoA
Return which backend is active (simulated or live) and the tools this server exposes.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
The tools mostly target distinct stages of the protein-design workflow: info, backbone generation, sequence design, and complex folding. The only overlap is design_binder, which is a convenience wrapper around design_backbone plus design_sequences, but its description makes that relationship clear.
Tool names are consistently snake_case and mostly follow an action-oriented pattern: design_backbone, design_sequences, design_binder, fold_complex. The lone outlier is info, which is a noun-only metadata tool, but it does not break readability.
Five tools is well-scoped for a focused protein/binder design server. Each tool has a clear role in the pipeline, and there is no redundant bloat beyond the intentional convenience wrapper.
The surface covers the core workflow: backbone design, sequence design, complex folding, optional affinity estimation, and a combined pipeline. Minor gaps remain around ranking/filtering designs and direct protein-protein affinity scoring, but agents can work around these using the returned confidence scores.
Maintenance
Related MCP Connectors
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
AI-powered bioprotocol optimization — generate, search, and manage lab protocols via MCP
Related MCP Servers
- AlicenseAqualityBmaintenanceA high-performance MCP server that gives LLMs access to 25 biomedical tools federated across 50+ upstream APIs for genes, variants, drugs, diseases, literature, clinical trials, and structural biology.43155 npm12Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to discover and execute tools via a secure MCP server with JWT authentication, RBAC, rate limiting, and audit logging.1MIT
- AlicenseAqualityCmaintenanceEnables AI harnesses to connect to a single MCP endpoint that routes to multiple downstream MCP servers, discovering and executing capabilities on demand while keeping tool schemas out of context.441 npmApache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables clients to connect once and access the union of multiple backend MCP servers' tools through a single unified interface, with namespaced tool routing, capability search, and health isolation.MIT