MCP 服务器

cesm-runner-mcp

MCP server for driving CESM case lifecycle: setup, build, submit, and monitor. Complements CrocoDash MCP for grid creation and forcing.

README

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