Colabfit MCP server

colabfit-mcp

An MCP server for discovering ColabFit datasets and training MACE interatomic potentials using KLIFF and KLAY.

Overview

This is a Model Context Protocol (MCP) server that gives AI assistants the ability to:

• Search and download scientific datasets from ColabFit
• Train MACE interatomic potentials on your local hardware (GPU or CPU)
• Run energy/forces calculations and validate models with OpenKIM test drivers

It bridges conversational AI and local compute — the AI agent searches for data, trains models, and runs simulations on your machine through this server.

Prerequisites

• Docker and Docker Compose v2 — for the containerized server
• Git — for cloning the repository
• make — for the quick-start commands (optional; manual steps are documented below)
• (Optional) NVIDIA GPU + drivers — for GPU-accelerated training
• (Optional) nvidia-container-toolkit — required for Docker to access the GPU

For local (non-Docker) installation, only Python 3.10+ is required. See Local Installation.

Setup

Quick Start (Recommended)

git clone https://github.com/colabfit/colabfit-mcp.git
cd colabfit-mcp

# One-time setup: creates data directories and .env file
make setup

# Build Docker images with your user ID for proper permissions
make build

Then register the MCP server with your client (see Register the MCP server below) and restart your client. The container starts automatically when your AI client connects.

Run make help to see all available commands.

Manual Setup

If you prefer not to use the Makefile:

1. Configure environment

cp example.env .env
# Edit .env to customize data directory location if desired

2. Create data directories

# Default location
mkdir -p ./colabfit_data/models ./colabfit_data/datasets ./colabfit_data/inference_output ./colabfit_data/test_driver_output

# Or custom location (must match COLABFIT_DATA_ROOT in .env)
# mkdir -p /your/custom/path/{models,datasets,inference_output,test_driver_output}

3. Build with user ID mapping

# This ensures the container user matches your host user and selects the right
# Dockerfile for your platform (CPU-only on macOS, GPU on Linux with NVIDIA)
USER_ID=$(id -u) GROUP_ID=$(id -g) ./start.sh build

Register the MCP server

start.sh automatically detects NVIDIA GPU availability and enables GPU passthrough when present, falling back to CPU otherwise.

Claude Code:

claude mcp add colabfit-mcp -- /path/to/colabfit-mcp/start.sh

Replace /path/to/colabfit-mcp with the absolute path to this repository. Then restart Claude Code for the new server to take effect.

Claude Desktop:

Add to your Claude Desktop config (Settings > Developer > Edit Config):

{
  "mcpServers": {
    "colabfit-mcp": {
      "command": "/path/to/colabfit-mcp/start.sh",
      "args": ["run", "--rm", "-i", "server"]
    }
  }
}

OpenAI Agent (API-based, not ChatGPT app):

OpenAI agents that support MCP can connect to this server over stdio by launching the same command used above.

Use this command as the MCP server entrypoint:

/path/to/colabfit-mcp/start.sh

If your agent framework requires explicit command/args fields, use:

{
  "command": "/path/to/colabfit-mcp/start.sh",
  "args": ["run", "--rm", "-i", "server"]
}

Notes:

Shortened. The full README is on GitHub.