Skip to main content
Glama

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

CLI input and output

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.py

Run 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 docs/validation.md

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

design_backbone

RFdiffusion

Design a protein backbone against a target (contigs, optional hotspot residues)

design_sequences

ProteinMPNN

Design amino-acid sequences that fold to a backbone

fold_complex

Boltz-2

Co-fold protein chains (and optional ligands), with an optional affinity estimate

design_binder

RFdiffusion + ProteinMPNN

Backbone then sequences in one call

info

—

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/v1

Hosted 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 simulator

License

Apache-2.0. This project calls NVIDIA BioNeMo NIMs but is not affiliated with or endorsed by NVIDIA.

Available Tools

5 tools
design_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

    A3.7/5.0

    Scored across 5 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A 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.
      43
      155 npm
      12
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      4
      41 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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