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

# Start with GPU detection (CUDA → CPU fallback)
make start

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:

• This is for OpenAI API-based agent runtimes that support MCP server registration.
• The ChatGPT consumer app (including non-Pro accounts) does not provide local stdio MCP server registration in the same way as developer agent runtimes.
• Replace /path/to/colabfit-mcp with the absolute path to this repository.

Generic MCP Client Setup

The server uses standard MCP stdio transport and works with any MCP-compatible client.

**En

... View full README on GitHub