gem-flux-mcp

jplfaria/gem-flux-mcp

3.1

If you are the rightful owner of gem-flux-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

Gem-Flux MCP Server is a Model Context Protocol server designed to facilitate secure and efficient communication between models and clients using modern authentication and transport protocols.

Gem-Flux MCP Server

A Model Context Protocol (MCP) server for genome-scale metabolic modeling with ModelSEEDpy and COBRApy

Tests Python 3.11

Build, gapfill, and analyze metabolic models through an AI-friendly Model Context Protocol interface.

Quick Start

Prerequisites

  • Python 3.11 (NOT 3.12+) - Python 3.12+ breaks scikit-learn dependency
  • UV package manager - Installation guide
  • ModelSEED database files - Download instructions below

1. Install

git clone https://github.com/jplfaria/gem-flux-mcp.git
cd gem-flux-mcp
uv sync

2. Download Database Files

mkdir -p data/database data/templates

# ModelSEED database (33,993 compounds, 43,775 reactions)
wget -O data/database/compounds.tsv https://raw.githubusercontent.com/ModelSEED/ModelSEEDDatabase/master/Biochemistry/compounds.tsv
wget -O data/database/reactions.tsv https://raw.githubusercontent.com/ModelSEED/ModelSEEDDatabase/master/Biochemistry/reactions.tsv

# Templates (from ModelSEEDpy installation)
cp .venv/lib/python3.11/site-packages/modelseedpy/templates/*.json data/templates/

3. Start Server

./start-server.sh

Expected output:

[INFO] Loading ModelSEED database from ./data/database
[INFO] Loaded 33,993 compounds, 43,775 reactions
[INFO] Server ready - accepting MCP requests

Features

Core Modeling:

  • Template-based model building from protein sequences
  • Two-stage gapfilling (ATP correction + genome-scale)
  • Flux balance analysis with detailed flux distributions
  • Growth media creation from ModelSEED compound IDs

Database Integration:

  • Search 33,993 compounds and 43,775 reactions
  • Lookup by name, formula, EC number, or pathway
  • Cross-reference to KEGG, BiGG, MetaCyc, ChEBI

Session Management:

  • In-memory model and media storage
  • List, filter, and delete models
  • Predefined media library (glucose, pyruvate, aerobic/anaerobic)

MCP Tools

Gem-Flux provides 11 MCP tools organized in three categories:

Core Modeling Tools (4)

  1. build_media - Create growth medium from compound IDs
  2. build_model - Build metabolic model from protein sequences
  3. gapfill_model - Add reactions to enable growth
  4. run_fba - Execute flux balance analysis

Database Lookup Tools (4)

  1. get_compound_name - Lookup compound by ID
  2. search_compounds - Search compounds by name/formula
  3. get_reaction_name - Lookup reaction by ID
  4. search_reactions - Search reactions by name/EC/pathway

Session Management Tools (3)

  1. list_models - List all models in session
  2. delete_model - Remove model from session
  3. list_media - List all media in session

Detailed tool documentation: See

Example Workflow

Complete workflow from protein sequences to flux predictions:

from gem_flux_mcp.tools import build_model, gapfill_model, run_fba

# 1. Build draft model from protein sequences
model = await build_model(
    protein_sequences={
        "prot_001": "MKLVINLVGNSGLGKSTFTQRLIN...",
        "prot_002": "MKQHKAMIVALERFRKEKRDAALL..."
    },
    template="GramNegative",
    model_name="E_coli_K12"
)
# Returns: model_id="E_coli_K12.draft"

# 2. Gapfill for growth in glucose minimal media
gapfilled = gapfill_model(
    model_id="E_coli_K12.draft",
    media_id="glucose_minimal_aerobic",  # Predefined media
    target_growth_rate=0.01
)
# Returns: model_id="E_coli_K12.draft.gf", reactions_added=5

# 3. Run FBA to predict fluxes
fba = run_fba(
    model_id="E_coli_K12.draft.gf",
    media_id="glucose_minimal_aerobic"
)
# Returns: objective_value=0.874 (growth rate in hr⁻¹)

More examples: See for Jupyter notebook examples

Installation

System Requirements

  • Python: 3.11.x only (3.12+ breaks dependencies)
  • Memory: 4 GB minimum, 8 GB recommended
  • Disk: 2 GB (includes database files)

Why Python 3.11?

Python 3.12+ removed distutils, breaking scikit-learn 1.2.0 (ModelSEEDpy dependency). Use Python 3.11.x.

# Check version
python --version  # Must be 3.11.x

# Install Python 3.11
brew install python@3.11          # macOS
sudo apt install python3.11       # Ubuntu/Debian

Installing UV

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify
uv --version

Usage

Starting the Server

# Basic start
./start-server.sh

# Custom host/port
export GEM_FLUX_HOST=0.0.0.0
export GEM_FLUX_PORT=9090
./start-server.sh

# Manual start
uv run python -m gem_flux_mcp.server

Connecting to Server

The server uses Model Context Protocol (MCP) with JSON-RPC 2.0 transport.

MCP Request Example:

{
  "jsonrpc": "2.0",
  "id": "call_123",
  "method": "tools/call",
  "params": {
    "name": "build_media",
    "arguments": {
      "compounds": ["cpd00027", "cpd00007"],
      "default_uptake": 100.0
    }
  }
}

Integration with StructBioReasoner

Gem-Flux MCP integrates seamlessly with StructBioReasoner, enabling metabolic modeling within multi-agent protein engineering workflows.

Quick Setup:

  1. Add Gem-Flux MCP server to StructBioReasoner config
  2. Create MetabolicModeler agent (optional)
  3. Use gem-flux tools from any agent

Full guide:

Optional: LLM Integration with Argo

Enable natural language interaction via Argo LLM Gateway:

# Install argo-proxy (separate from gem-flux-mcp)
pip install argo-proxy

# Start proxy
argo-proxy  # Port 8000

# Use ArgoMCPClient
from gem_flux_mcp.argo_client import ArgoMCPClient
client = ArgoMCPClient()
client.initialize_sync()
response = client.chat("Build a model for E. coli genome 83333.1")

Note: Argo is optional. Gem-Flux works without it for Python API and MCP integration.

Full guide:

Configuration

Configure via environment variables:

# Server binding
export GEM_FLUX_HOST="localhost"     # Default: localhost
export GEM_FLUX_PORT="8080"          # Default: 8080

# Resource paths
export GEM_FLUX_DATABASE_DIR="./data/database"
export GEM_FLUX_TEMPLATE_DIR="./data/templates"

# Logging
export GEM_FLUX_LOG_LEVEL="INFO"    # DEBUG, INFO, WARNING, ERROR
export GEM_FLUX_LOG_FILE="./gem-flux.log"

# Storage limits
export GEM_FLUX_MAX_MODELS="100"
export GEM_FLUX_MAX_MEDIA="50"

Development

Running Tests

# All tests (785 tests, 90% coverage)
uv run pytest

# Specific test types
uv run pytest tests/unit/           # Unit tests only
uv run pytest tests/integration/    # Integration tests only

# With coverage
uv run pytest --cov=src --cov-report=html

Code Quality

uv run ruff check src/      # Linting
uv run mypy src/            # Type checking
uv run black src/           # Formatting

Troubleshooting

Common Issues

Python 3.12+ error:

ModuleNotFoundError: No module named 'distutils'

Solution: Use Python 3.11.x (see Installation)

Database not found:

[ERROR] Database file not found: data/database/compounds.tsv

Solution: Download database files (see Quick Start)

Template not found:

[ERROR] Required template missing: GramNegModelTemplateV6.json

Solution: Copy templates from ModelSEEDpy installation

cp .venv/lib/python3.11/site-packages/modelseedpy/templates/*.json data/templates/

Gapfilling infeasible:

InfeasibilityError: Cannot find reactions to enable growth

Solutions:

  • Try richer media (more compounds)
  • Lower target_growth_rate (default: 0.01)
  • Verify media composition with list_media()

Debug mode:

export GEM_FLUX_LOG_LEVEL=DEBUG
./start-server.sh

Documentation

Tool Documentation:

  • - Complete tool reference
  • - Model building guide
  • - Gapfilling guide
  • - FBA execution guide

Integration Guides:

Specifications:

  • - Architecture
  • - Data structures
  • - 20 cleanroom specifications

Development:

  • - Testing guide
  • - ATP correction feature
  • - AI development guidelines

Contributing

We welcome contributions! Key requirements:

  • Python 3.11 with type hints
  • Tests first (TDD) - maintain ≥80% coverage
  • All tests pass - uv run pytest returns 0
  • Code quality - ruff check and mypy pass
  • Google-style docstrings

See for detailed guidelines.

License

MIT License - See

Support

Acknowledgments

Built with:

  • ModelSEEDpy - Metabolic model building
  • COBRApy - Constraint-based modeling
  • FastMCP - MCP server framework
  • UV - Python package manager

Data:

Status: Production-ready MVP v0.1.0 Last Updated: November 4, 2025