cesm-runner-mcp

MCP server for driving CESM case lifecycle: setup → build → submit → monitor.

Complements the CrocoDash MCP, which handles grid creation and forcing. This server picks up where that one leaves off — once a case directory exists, this server drives the CIME build/run pipeline.

Tools

Case inspection

Case lifecycle

All three accept an optional container=<session_name> arg to run inside a crocontainer session instead of on the host.

XML config

Monitoring

Container management (crocontainer fast-iteration path)

Related MCP server: pycycle-mcp

Resources

Setup

pip install -e .
# or in the CrocoDash conda env:
conda run -n CrocoDash pip install -e .

Running

cesm-runner-mcp
# or
python server.py

Wire up to Claude Code by adding to .mcp.json:

{
  "mcpServers": {
    "cesm-runner": {
      "command": "python",
      "args": ["/path/to/MCP_cesm_runner/server.py"]
    }
  }
}

Fast iteration with crocontainer

Instead of waiting in the PBS queue, run CESM interactively inside a container. On Derecho, the full GLADE filesystem is mounted transparently so all host paths work inside.

One-time setup (Derecho)

# Build the writable sandbox (~1 hr on a compute node)
# Or call build_sandbox() via the MCP
qcmd -l walltime=03:00:00 -- apptainer build --sandbox \
  /glade/derecho/scratch/$USER/crocontainer_sandbox \
  docker://ghcr.io/crocodile-cesm/crocontainer:latest-amd64

Typical MCP session

start_container(scratch_dir="~/scratch/croc_scratch")
  → Apptainer instance starts; /glade mounted; inputdata at /glade/campaign/cesm/cesmdata/inputdata

case_setup("~/croc_cases/mycase", container="croc_session")
case_build("~/croc_cases/mycase", container="croc_session")
  → compiles interactively, no queue

xmlchange("~/croc_cases/mycase", "STOP_N", "3")
case_submit("~/croc_cases/mycase", no_batch=True, container="croc_session")
  → runs synchronously; returns output in seconds

# Debugger MCP finds an error → fix → resubmit in the same conversation:
xmlchange("~/croc_cases/mycase", "DT", "900")
case_submit("~/croc_cases/mycase", no_batch=True, container="croc_session")

stop_container("croc_session")

Inputdata on Derecho

CESM inputdata is mounted directly from GLADE — no downloading required: /glade/campaign/cesm/cesmdata/inputdata → /root/cesm/inputdata inside container

On a laptop (Podman)

start_container(
  scratch_dir="./scratch",
  sandbox_or_image="ghcr.io/crocodile-cesm/crocontainer:latest",
  inputdata_dir="./cesm_nyf_inputdata",   # pre-downloaded NYF data
  runtime="podman"
)

Design

• Stateless: each tool reads from the filesystem; no in-memory state

• Shells out to CIME scripts: uses ./xmlquery, ./case.setup, etc. directly — version-safe and matches what users run manually

• Works with any CESM install: not specific to CrocoDash or MOM6

• Container-aware: lifecycle tools accept container= to route via apptainer exec instance:// or podman exec instead of running on the host

CESM install on Derecho

Default reference install: ~/work/installs/cesm3_maddd_new

Cases live in: ~/croc_cases/

CESM inputdata: /glade/campaign/cesm/cesmdata/inputdata