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

| Tool | Purpose | |------|---------| | list_cases(search_root) | Find all CESM cases under a directory | | get_case_status(case_dir) | Read CaseStatus log + key XML config | | check_input_data(case_dir) | Verify all required input files are staged |

Case lifecycle

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

| Tool | Purpose | |------|---------| | case_setup(case_dir, [container]) | Run ./case.setup | | case_build(case_dir, [container]) | Compile the model (./case.build) | | case_submit(case_dir, no_batch, [container]) | Submit to PBS/slurm or run interactively |

XML config

| Tool | Purpose | |------|---------| | xmlquery(case_dir, variable) | Query any CESM XML variable | | xmlchange(case_dir, variable, value) | Set a CESM XML variable | | preview_run(case_dir) | Show PE layout and batch script without submitting |

Monitoring

| Tool | Purpose | |------|---------| | tail_log(case_dir, component, lines) | Read recent run log output | | get_job_status(case_dir) | Check PBS/slurm queue for this case's job | | list_compsets(cesmroot, filter) | List available compsets in a CESM install |

Container management (crocontainer fast-iteration path)

| Tool | Purpose | |------|---------| | build_sandbox([sandbox_dir]) | One-time: build Apptainer sandbox from registry image (~1hr on Derecho) | | start_container(scratch_dir, [sandbox_or_image, inputdata_dir, name, runtime]) | Start a persistent container session | | container_exec(name, case_dir, command) | Run any command inside a running session | | stop_container(name) | Stop and clean up the session | | list_containers() | Show running sessions |

Resources

| URI | Content | |-----|---------| | cesm://case/{case_dir}/env | All XML config variables | | cesm://case/{case_dir}/status | CaseStatus log | | cesm://case/{case_dir}/logs | List of run log files |

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