ModelSEED API

Modern REST API backend for the ModelSEED metabolic modeling platform. Replaces the legacy Perl-based ProbModelSEED JSON-RPC service with a Python FastAPI application.

The API handles model listing, reconstruction, gapfilling, FBA, biochemistry queries, and PATRIC workspace operations. Long-running jobs (model building, gapfilling, FBA) run as Celery tasks in production or as subprocesses in local development.

The user-facing web frontend is a separate Next.js/TypeScript application deployed at https://modelseed.org. This repo also ships a lightweight demo dashboard (/demo/) used for development and manual testing of the API; it is not the production UI.

Live API

The production API is served at https://modelseed.org/PMS/.

URL	Description
https://modelseed.org/PMS/docs	Swagger API docs (interactive)
https://modelseed.org/PMS/redoc	ReDoc API docs (readable)
https://modelseed.org/PMS/openapi.json	OpenAPI spec
https://modelseed.org/PMS/api/health	Health check

Biochemistry endpoints are public, so the API can be exercised without an account:

curl https://modelseed.org/PMS/api/health
curl 'https://modelseed.org/PMS/api/biochem/stats'
curl 'https://modelseed.org/PMS/api/biochem/search?query=glucose&type=compounds&limit=5'

Model, job, media, and workspace endpoints require a PATRIC token (see Authentication).

Run standalone (your own machine, no ANL setup)

The repo ships a self-contained Docker image. It bundles all dependencies and the biochemistry database; no PATRIC account, RAST account, or ANL infrastructure is needed for the local-mode workflow.

docker run -p 8000:8000 ghcr.io/modelseed/modelseed-api:latest

Or build the same image from source, which needs nothing but this repo and network access (the Dockerfile clones the dependency repos itself):

git clone https://github.com/ModelSEED/modelseed-api.git
cd modelseed-api
docker build -f Dockerfile.standalone -t modelseed-api .
docker run -p 8000:8000 modelseed-api

Then open http://localhost:8000/demo/ or hit the API directly:

curl http://localhost:8000/api/health
curl 'http://localhost:8000/api/biochem/search?query=glucose&type=compounds&limit=5'

To persist models across container restarts, bind-mount a host directory:

docker run -p 8000:8000 \
    -v ~/.modelseed:/data/modelseed \
    ghcr.io/modelseed/modelseed-api:latest

The standalone image defaults to local-filesystem storage. Endpoints that need ANL infrastructure (/api/workspace/*, /api/rast/*) return a clean 503 unless their env vars are configured. See docs/STANDALONE.md for the full walkthrough including FASTA-to-model recipes and MCP server setup for Claude Desktop.

API Endpoints

Most endpoints require a PATRIC token in the Authorization header (not needed in local mode). Biochemistry endpoints are always public.

Health

Method	Path	Auth	Description
`GET`	`/api/health`	No	Returns `{"status":"ok","version":"1.0.0"}`

Models (`/api/models`)

Method	Path	Description
`GET`	`/api/models`	List user's models
`GET`	`/api/models/data?ref=`	Full model detail: reactions, compounds, genes, biomasses
`POST`	`/api/models/edit`	Atomic editing: add/remove/modify reactions, compounds, biomass
`POST`	`/api/models/copy`	Copy a model to a new workspace path
`DELETE`	`/api/models?ref=`	Delete a model
`GET`	`/api/models/export?ref=&format=`	Export as `json`, `sbml`, `cobra-json`
`GET`	`/api/models/gapfills?ref=`	List gapfill solutions
`POST`	`/api/models/gapfills/manage`	Integrate, unintegrate, or delete gapfill solutions
`GET`	`/api/models/fba?ref=`	List FBA studies for a model
`GET`	`/api/models/fba/data?ref=&fba_id=`	Get FBA result with reaction fluxes
`GET`	`/api/models/edits?ref=`	List edit history (stub: returns `[]`)

Jobs (`/api/jobs`)

Method	Path	Description
`GET`	`/api/jobs`	Check job statuses (supports `ids` filter and status filters)
`POST`	`/api/jobs/reconstruct`	Build a metabolic model from a BV-BRC genome ID, a FASTA upload, or a RAST job ID
`POST`	`/api/jobs/bulk_reconstruct`	Build models for many genomes in one job (see `docs/BULK_RECONSTRUCT.md`)
`POST`	`/api/jobs/gapfill`	Gapfill a model against a media condition
`POST`	`/api/jobs/fba`	Run flux balance analysis
`POST`	`/api/jobs/merge`	Merge multiple models (not yet implemented, returns HTTP 501)
`POST`	`/api/jobs/manage`	Delete jobs (rerun accepted but not yet implemented)

Biochemistry (`/api/biochem`, no auth)

Method	Path	Description
`GET`	`/api/biochem/stats`	Compound and reaction counts
`GET`	`/api/biochem/reactions?ids=`	Get reactions by comma-separated IDs
`GET`	`/api/biochem/compounds?ids=`	Get compounds by comma-separated IDs
`GET`	`/api/biochem/search?query=&type=`	Search compounds or reactions (limit up to 200)

RAST (`/api/rast`)

Method	Path	Description
`GET`	`/api/rast/jobs`	List user's legacy RAST annotation jobs (RAST token required)
`GET`	`/api/rast/genome`	Fetch a RAST-annotated genome translated to KBase Genome shape

Media (`/api/media`)

Method	Path	Description
`GET`	`/api/media/public`	List public media formulations
`GET`	`/api/media/mine`	List user's custom media
`GET`	`/api/media/export?ref=`	Export a media condition

Workspace proxy (`/api/workspace`)

All workspace operations are POST-based proxies to the PATRIC Workspace service.

Method	Path	Description
`POST`	`/api/workspace/ls`	List workspace contents
`POST`	`/api/workspace/get`	Get workspace objects (supports `metadata_only`)
`POST`	`/api/workspace/create`	Create workspace objects
`POST`	`/api/workspace/copy`	Copy or move workspace objects
`POST`	`/api/workspace/delete`	Delete workspace objects
`POST`	`/api/workspace/metadata`	Update workspace object metadata
`POST`	`/api/workspace/download-url`	Get download URLs
`POST`	`/api/workspace/permissions`	List permissions

Authentication

Biochemistry endpoints (/api/biochem/*) and /api/health are public. Everything else requires a PATRIC token passed in the Authorization header. In local-storage mode (see below) no authentication is required at all.

To obtain a token:

Log in at https://www.bv-brc.org
Open the browser console (F12)
Run copy(TOKEN) to copy the token to your clipboard

Then send it with each request:

curl -H "Authorization: $PATRIC_TOKEN" https://modelseed.org/PMS/api/models

Tokens expire; if previously working calls start returning 401, request a fresh one.

MCP Server (AI assistant interface)

The MCP server exposes ModelSEED tools to AI assistants via the Model Context Protocol. Runs in local storage mode only (no PATRIC account, no auth tokens, no network beyond BV-BRC genome fetching).

MCP tools call the same service layer as the REST API directly (no HTTP overhead, identical behavior).

Run

python -m modelseed_mcp
# or, after pip install:
modelseed-mcp

Claude Desktop / Claude Code config

{
  "mcpServers": {
    "modelseed": {
      "command": "python",
      "args": ["-m", "modelseed_mcp"],
      "env": {
        "MODELSEED_MODELSEED_DB_PATH": "/path/to/ModelSEEDDatabase",
        "MODELSEED_TEMPLATES_PATH": "/path/to/ModelSEEDTemplates/templates/v7.0",
        "MODELSEED_CB_ANNOTATION_ONTOLOGY_API_PATH": "/path/to/cb_annotation_ontology_api"
      }
    }
  }
}

MCP tools (17)

Group	Tools
Biochemistry	`search_compounds`, `search_reactions`, `get_compound`, `get_reaction`
Models	`list_models`, `get_model`, `delete_model`, `copy_model`, `export_model`, `edit_model`
Media	`list_media`, `get_media`
Async jobs	`build_model`, `gapfill_model`, `run_fba`, `merge_models`, `check_job`

Async tools dispatch jobs via subprocess and poll until completion. Set wait=False to get the job ID immediately and poll manually with check_job.

Run it locally

This route builds from source against the dependency forks. If you just want a working server, prefer the standalone image above, which does all of this for you.

Requires Python 3.11+ (or Docker).

1. Clone required repositories

The build context expects all dependency repos as siblings of modelseed-api/.

mkdir modelseed && cd modelseed
git clone https://github.com/ModelSEED/modelseed-api.git
git clone -b main https://github.com/cshenry/ModelSEEDpy.git
git clone https://github.com/cshenry/KBUtilLib.git
git clone https://github.com/Fxe/cobrakbase.git
git clone -b dev https://github.com/ModelSEED/ModelSEEDDatabase.git
git clone https://github.com/ModelSEED/ModelSEEDTemplates.git
git clone https://github.com/kbaseapps/cb_annotation_ontology_api.git

2a. Docker (recommended)

docker compose -f modelseed-api/docker-compose.yml up --build

2b. Manual

pip install -e cobrakbase
pip install -e ModelSEEDpy
pip install -e KBUtilLib
pip install -e "modelseed-api[modeling]"

Configure data paths:

cd modelseed-api
cat > .env << EOF
MODELSEED_MODELSEED_DB_PATH=$(realpath ../ModelSEEDDatabase)
MODELSEED_TEMPLATES_PATH=$(realpath ../ModelSEEDTemplates/templates/v7.0)
MODELSEED_CB_ANNOTATION_ONTOLOGY_API_PATH=$(realpath ../cb_annotation_ontology_api)
EOF

Start the server:

cd src && python -m uvicorn modelseed_api.main:app --host 0.0.0.0 --port 8000

2c. Local mode (no PATRIC account needed)

To run without PATRIC Workspace, use the local storage backend. Models are stored as JSON files on disk.

cat >> modelseed-api/.env << EOF
MODELSEED_STORAGE_BACKEND=local
MODELSEED_LOCAL_DATA_DIR=~/.modelseed/data
EOF

In local mode, no authentication is required. Public media formulations are bundled in data/media/public/.

3. Verify it's running

After starting the server (any of 2a / 2b / 2c), it listens on port 8000:

URL	Description
http://localhost:8000/api/health	Health check
http://localhost:8000/docs	Swagger API docs
http://localhost:8000/redoc	ReDoc API docs
http://localhost:8000/demo/	Demo dashboard

4. Get a PATRIC token (workspace mode only)

Follow Authentication above, then paste the token into the demo page's token field or send it as the Authorization header. Local mode needs no token.

Architecture

This repo contains two interfaces to the same modeling engine:

                      Shared Service Layer
                      (biochem_service, ModelService, JobDispatcher,
                       export_service, JobStore, storage_factory)
                              |
            ----------------------------------
            |                                |
       REST API (HTTP)                  MCP Server
       modelseed_api                    modelseed_mcp
       FastAPI + uvicorn                FastMCP (stdio)
            |                                |
       Browser / Frontend              AI Assistants
       (PATRIC auth tokens)            (Claude, etc., local mode)

REST API (modelseed_api): HTTP endpoints for browsers and frontends. Supports both PATRIC Workspace and local storage. Requires auth tokens for workspace mode.

MCP Server (modelseed_mcp): MCP interface for AI assistants. Local storage mode only. No auth, no network dependencies. Calls the same service layer directly.

Key design decisions:

Synchronous API: long-running operations are dispatched to external job scripts or Celery tasks
Pluggable storage: a factory selects PATRIC Workspace (storage_backend=workspace) or local filesystem (storage_backend=local); both implement the same interface
Fully offline local mode: with storage_backend=local, no PATRIC account or network access is needed; models are stored as JSON files on disk
Local templates: model templates are loaded from git repos on disk, not from KBase workspace
No KBase dependency: runs entirely against BV-BRC/PATRIC APIs

REST API vs MCP

	REST API	MCP Server
Client	Browsers, frontends, scripts	AI assistants
Transport	HTTP (port 8000)	stdio (Model Context Protocol)
Auth	PATRIC tokens (workspace mode)	None (local mode only)
Storage	Workspace or local	Local only
Install	`pip install -e ".[modeling]"`	`pip install -e ".[modeling,mcp]"`

Demo dashboard

The demo dashboard at /demo/ is a single-page HTML app for exercising the API by hand during development. It is not the production frontend. When running locally or from the standalone image it is at http://localhost:8000/demo/.

Tab	What it does
My Models	List models, view detail, export, gapfill, run FBA
Build Model	Build a new model from a BV-BRC genome ID with optional gapfilling
Public Media	Browse available media formulations
Biochemistry	Search compounds and reactions
Jobs	Monitor running, completed, and failed jobs
Workspace	Browse PATRIC workspace paths

Dependencies

Required repositories

Repository	Branch	Purpose
cshenry/ModelSEEDpy	`main`	Core modeling engine (cshenry fork has `ModelSEEDBiochem.get(path=)` and MSFBA)
ModelSEED/ModelSEEDDatabase	`dev`	Biochemistry data (compounds, reactions, aliases)
ModelSEED/ModelSEEDTemplates	`main`	Model templates v7.0 (Core, GramPos, GramNeg)
cshenry/KBUtilLib	`main`	BVBRCUtils (genome fetch), MSReconstructionUtils (model build)
kbaseapps/cb_annotation_ontology_api	`main`	Ontology data for genome annotation
Fxe/cobrakbase	`master`	KBase object factory and FBAModel builder (0.4.0; pip 0.3.0 lacks `_build_object()`)

Python packages

Core dependencies (see pyproject.toml):

fastapi + uvicorn: web framework and ASGI server
cobra: constraint-based modeling (FBA, SBML I/O)
modelseedpy: ModelSEED modeling engine (cshenry fork)
kbutillib: KBase/BV-BRC utility library
cobrakbase: KBase/cobra bridge
requests: HTTP client for workspace and BV-BRC API calls
pydantic-settings: configuration management
celery[redis]: job scheduling (production mode only)
fastmcp: MCP server framework (optional)

Job scheduling

Two modes controlled by MODELSEED_USE_CELERY (default: false):

Local (development): jobs run as subprocesses via src/job_scripts/. Job state is stored as JSON files in /tmp/modelseed-jobs/. No external infrastructure needed.
Production: jobs are dispatched via Celery to a Redis broker. The Celery task implementations in src/modelseed_api/jobs/tasks.py mirror the subprocess job scripts for full parity.

Setting	Value
Broker	configured via `MODELSEED_CELERY_BROKER_URL` (Redis)
Queue	`modelseed`
Time limit	4 hours

To enable Celery mode, set MODELSEED_USE_CELERY=true in .env. Start the worker:

cd src && celery -A modelseed_api.jobs.celery_app worker -Q modelseed --loglevel=info

Configuration

All settings load from environment variables with the MODELSEED_ prefix or from a .env file. See .env.example for the full list.

Variable	Default	Description
`MODELSEED_HOST`	`0.0.0.0`	Server bind address
`MODELSEED_PORT`	`8000`	Server port
`MODELSEED_DEBUG`	`false`	Enable debug mode
`MODELSEED_CORS_ORIGINS`	`["*"]`	Allowed CORS origins (JSON list)
`MODELSEED_STORAGE_BACKEND`	`workspace`	`workspace` (PATRIC) or `local` (filesystem)
`MODELSEED_LOCAL_DATA_DIR`	`~/.modelseed/data`	Local storage directory (local mode)
`MODELSEED_MODELSEED_DB_PATH`	required	Path to ModelSEEDDatabase repo
`MODELSEED_TEMPLATES_PATH`	required	Path to ModelSEEDTemplates/templates/v7.0
`MODELSEED_CB_ANNOTATION_ONTOLOGY_API_PATH`	required	Path to cb_annotation_ontology_api repo
`MODELSEED_WORKSPACE_URL`	`https://p3.theseed.org/services/Workspace`	PATRIC workspace URL
`MODELSEED_WORKSPACE_TIMEOUT`	`1800`	Workspace HTTP request timeout (seconds)
`MODELSEED_PUBLIC_MEDIA_PATH`	`/chenry/public/modelsupport/media`	Workspace path for public media
`MODELSEED_USE_CELERY`	`false`	Use Celery+Redis for job dispatch
`MODELSEED_CELERY_BROKER_URL`	`redis://bioseed_redis:6379/10`	Celery Redis broker URL
`MODELSEED_CELERY_RESULT_BACKEND`	`redis://bioseed_redis:6379/10`	Celery Redis result backend URL
`MODELSEED_JOB_STORE_DIR`	`/tmp/modelseed-jobs`	Directory for job state files
`MODELSEED_RAST_JOBS_DIR`	(empty)	Filesystem path to RAST job dirs (`/api/rast/genome`). Leave empty to disable.
`MODELSEED_RAST_DB_HOST`	(empty)	RAST job database host (`/api/rast/jobs`). Leave empty to disable.
`MODELSEED_RAST_DB_PORT`	`3306`	RAST job database port
`MODELSEED_RAST_DB_USER`	(empty)	RAST job database user
`MODELSEED_RAST_DB_PASSWORD`	(empty)	RAST job database password
`MODELSEED_RAST_DB_NAME`	`RastProdJobCache`	RAST job database name

Project structure

src/
  modelseed_api/              # FastAPI application (REST API)
    main.py                   # App initialization
    config.py                 # Settings (pydantic-settings)
    auth/dependencies.py      # PATRIC/RAST token extraction
    routes/                   # API endpoint definitions
    schemas/                  # Pydantic request/response models
    services/                 # Business logic (shared with MCP)
      storage_factory.py      #   WorkspaceService or LocalStorageService
      workspace_service.py    #   PATRIC workspace proxy
      local_storage_service.py#   Filesystem storage backend
      model_service.py        #   Model CRUD, gapfill management
      biochem_service.py      #   ModelSEEDDatabase queries
      export_service.py       #   SBML / CobraPy export
      bulk_export.py          #   Bulk model export
      genome_annotator.py     #   FASTA annotation via RAST
      preflight.py            #   Request validation before job dispatch
      rast_service.py         #   RAST endpoints (direct MySQL + filesystem)
      rast_figv_reader.py     #   Reads RAST job dirs off the filesystem
    jobs/                     # Job dispatch (shared with MCP)
      dispatcher.py           #   Subprocess or Celery dispatch
      store.py                #   Job state (JSON files)
      celery_app.py
      tasks.py                #   Celery task definitions
    static/index.html         # Demo dashboard
  modelseed_mcp/              # MCP server (AI assistant interface)
    server.py                 # FastMCP instance + tool registration
    tools/                    # MCP tool definitions
  job_scripts/                # External scripts for long-running ops
    reconstruct.py
    bulk_reconstruct.py
    gapfill.py
    run_fba.py
data/
  media/public/               # Bundled public media formulations
docs/
  STANDALONE.md               # Standalone container walkthrough
  BULK_RECONSTRUCT.md         # Bulk reconstruction guide
  WORKAROUNDS.md              # Active workarounds with upstream status
  KNOWN_GAPS.md               # Known gaps and follow-ups
  API_ONBOARDING.md           # Onboarding guide for frontend developers
  E2E_TEST_PLAN.md            # End-to-end test plan
tests/
  conftest.py
  test_live_integration.py    # Integration tests against live workspace
  test_auth.py                # Auth dependency unit tests
  test_mcp/                   # MCP tool unit tests
  live/                       # Layered live test suite (smoke / functional / biological / ui)

Testing

pip install -e ".[dev]"
pytest

A bare pytest run only collects the hermetic suite (unit/routes/integration/e2e/mcp) and never touches the network. The layered live E2E suite against a deployed stack (smoke/functional/biological/ui) is opt-in and requires a MODELSEED_TEST_TOKEN; see docs/E2E_TEST_PLAN.md for pytest -m live_smoke and friends.

Workarounds

A small number of upstream-fix-needed workarounds are tracked in docs/WORKAROUNDS.md with current upstream status. Most prior workarounds have been merged upstream as of 2026-05.

Contributing

See CONTRIBUTING.md. Open issues and pull requests at https://github.com/ModelSEED/modelseed-api/issues.

Deployment and on-call runbooks for the ANL-hosted instance are maintained separately by the ModelSEED team and are not part of this repository. For questions about the hosted deployment, open an issue.

Citing

If you use this software, please cite the ModelSEED v2 paper:

Faria, J.P., Liu, F., Edirisinghe, J.N., Gupta, N., Seaver, S.M.D., Freiburger, A.P., Setlur, V., Zhang, Q., Weisenhorn, P., Conrad, N., Zarecki, R., Song, H.-S., DeJongh, M., Best, A.A., Cottingham, R.W., Arkin, A.P., and Henry, C.S. (2026). ModelSEED v2: High-throughput genome-scale metabolic model reconstruction with enhanced energy biosynthesis pathway prediction. bioRxiv. https://doi.org/10.1101/2023.10.04.556561

To cite this specific software repository/version, see CITATION.cff (also picked up by GitHub's "Cite this repository" button and Zenodo).

License

MIT

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
data/media/public		data/media/public
docs		docs
scripts		scripts
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CITATION.cff		CITATION.cff
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
Dockerfile.standalone		Dockerfile.standalone
LICENSE		LICENSE
README.md		README.md
docker-build.sh		docker-build.sh
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml

Latest commit

History

Folders and files

Repository files navigation

ModelSEED API

Live API

Run standalone (your own machine, no ANL setup)

API Endpoints

Health

Models (/api/models)

Jobs (/api/jobs)

Biochemistry (/api/biochem, no auth)

RAST (/api/rast)

Media (/api/media)

Workspace proxy (/api/workspace)

Authentication

MCP Server (AI assistant interface)

Run

Claude Desktop / Claude Code config

MCP tools (17)

Run it locally

1. Clone required repositories

2a. Docker (recommended)

2b. Manual

2c. Local mode (no PATRIC account needed)

3. Verify it's running

4. Get a PATRIC token (workspace mode only)

Architecture

REST API vs MCP

Demo dashboard

Dependencies

Required repositories

Python packages

Job scheduling

Configuration

Project structure

Testing

Workarounds

Contributing

Citing

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Models (`/api/models`)

Jobs (`/api/jobs`)

Biochemistry (`/api/biochem`, no auth)

RAST (`/api/rast`)

Media (`/api/media`)

Workspace proxy (`/api/workspace`)