Boltz2 Tool Setup¶

This tutorial will Tutorial you through setting up and running MCP (Model Context Protocol) server-based tools for Boltz2 molecular docking.

Overview¶

This directory contains the following MCP server implementations:

boltz_MCP.py: Provides molecular docking capabilities using Boltz2

Prerequisites¶

Hardware Requirements¶

GPU: NVIDIA A100 or H100 GPU recommended

System Requirements¶

Linux-based system (tested on Ubuntu/CentOS)
CUDA-compatible GPU drivers
Network access for API calls

Setup Instructions¶

1. Environment Setup¶

# Create and activate conda environment for Boltz2
conda create -n tooluniverse-env python=3.11 -c conda-forge -y
conda activate tooluniverse-env

# Navigate to the Boltz repository
git clone https://github.com/jwohlwend/boltz.git
cd boltz

# Install Boltz2 in editable mode with CUDA support
pip install -e ".[cuda]"

2. Verify Boltz2 Installation¶

# Test Boltz2 installation
python -c "import boltz; print('Boltz2 installed successfully')"

# Verify CUDA support
python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')"

3. Install ToolUniverse and MCP Dependencies¶

# Return to parent directory from boltz subdirectory
cd ..

# Install compatible NumPy version first
pip install "numpy==2.0"

# Install ToolUniverse
git clone https://github.com/mims-harvard/ToolUniverse.git
cd ToolUniverse

python -m pip install . --no-cache-dir

# Install additional dependencies
pip install pyarrow fastparquet lxml
pip install -U sentence-transformers

4. Environment Configuration¶

Set Environment Variables¶

Set the required environment variables on the client machine where you’re calling the MCP tool from ToolUniverse (not on the GPU server where the tool is running):

# For Boltz2 server (running on port 8080)
export BOLTZ_MCP_SERVER_HOST="your-gpu-hostname"

Important: Set this variable on the machine where you’re executing your ToolUniverse code, even if the MCP server is running on a different GPU machine.

Finding your GPU hostname:

# Get current hostname by running this command on the GPU where your MCP server will run.
hostname

# Example hostnames:
# - gpu-node-01
# - compute-a100-001.cluster.edu
# - localhost (if running locally)

Running the MCP Server¶

1. Start Boltz2 MCP Server¶

# Start the Boltz2 MCP server on the GPU where you want it to run.
python path/to/boltz_mcp_server.py

The server will start on http://0.0.0.0:8080 but will be accessible via your GPU hostname (e.g., http://your-gpu-hostname:8080) and provide molecular docking capabilities.

Usage Examples¶

For comprehensive usage examples and testing patterns, please refer to the test file:

# View MCP tool usage examples
cat ToolUniverse/src/tooluniverse/test/test_mcp_tool.py

This test file contains detailed examples of how to interact with the Boltz2 molecular docking MCP servers, including proper API calls and parameter formatting.