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, but only for cases made for the container's CIME machine, ubuntu-latest (e.g. /workspace/case after run_case_in_container). A host case (machine=derecho) is refused: bundle it with bundle_case (CrocoDash MCP) and use run_case_in_container.

XML config

Monitoring

Container management (crocontainer fast-iteration path)

Resources

{case_dir*} takes the case path as-is, slashes included, e.g. cesm://case//glade/u/home/<user>/croc_cases/my_case/status.

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)

Call build_sandbox() via the MCP: it qsubs the build (Derecho develop queue, 3 h) and returns the job id and log path. build_sandbox(rebuild=True) replaces a stale sandbox, keeping the old one as <path>.old-<timestamp>. Or build it by hand:

# Build the writable sandbox (~1 hr on a compute node)
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

The container only builds and runs cases for its own CIME machine (ubuntu-latest), so a case made on Derecho goes in as a bundle, which run_case.sh forks for ubuntu-latest:

bundle_case("~/croc_cases/mycase", "~/scratch/croc_bundles")      # CrocoDash MCP

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

run_case_in_container("croc_session", "~/scratch/croc_bundles/mycase_case_bundle")
  → forks the case to /workspace/case, builds and runs it; no queue

# Debugger MCP finds an error → fix → resubmit inside the container:
container_exec("croc_session", "/workspace/case", "./xmlchange STOP_N=3")
case_submit("/workspace/case", 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/CESM_crocodash (CESM branch crocodash)

Cases live in: ~/croc_cases/

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