nes-lter-mcp

An MCP server for the NES-LTER API. It exposes efficient discovery, batch CTD queries, cruise datasets, schema discovery, and provenance-rich results.

Example prompt to an MCP client:

show me the profile for oxygen for station L8 for winter 2025

The server can satisfy this with query_ctd(station="L8", variable="oxygen", season="winter", year=2025).

Install / run

uv sync
uv run nes-lter-mcp

For MCP clients, configure the command as:

uv --directory /path/to/nes-lter-mcp run nes-lter-mcp

Related MCP server: erddap-mcp-demo

Tools

• list_stations() — station catalog with coordinates, depth, and provenance.

• find_cruises(year?, season?, cruise_type?) — full CTD cruise catalog when unfiltered, or cruises filtered by year/season/type. Results preserve the API fields from /api/ctd/cruises/all.

• list_casts(cruise_name, station?, max_distance_km?, offset?, limit?) — bounded cast discovery.

• get_cast_profile(cruise_name, cast_number, variable, include_points?, depth_min?, depth_max?) — one profile.

• query_ctd(...) — batch CTD query with surface_definition (shallowest_valid, mean_0_5m, mean_0_10m, or mean_0_20m) and optional depth_bin_m.

• get_station_profile(...) — compatibility wrapper around query_ctd.

• plot_ctd_profiles(...) — plotting-ready CTD records plus a Vega-Lite vertical-profile specification. Supports one or multiple variables, and aggregation=none, cruise_mean, or period_mean.

• list_dataset_rows(dataset, cruise_name, ...) — underway, bottles, bottle summaries, nutrients, HPLC, chlorophyll, events, and event history.

• query_underway(variable, cruise_name?, year?, season?, cruise_type?, aggregation?, start_time?, end_time?, ...) — vessel-aware underway query (wind, temperature, salinity, position, speed, etc.) across Endeavor, Neil Armstrong, Atlantis, Hugh R. Sharp, and Atlantic Explorer's differing column conventions, with aggregation=cruise_mean (default), period_mean, or none. Directional variables (wind_direction, heading, course_over_ground) use a circular mean.

• get_cruise_track(cruise_name) — track URL and provenance.

• get_cruise_track_data(cruise_name) — GeoJSON cruise track built from cast positions.

• make_station_map(stations?, cruises?, include_tracks?) — station GeoJSON and a Vega-Lite map specification.

• get_dataset_schema(dataset, cruise_name) — available columns or API schema.

• resolve_variable(name, cruise_name?, dataset?) — friendly-name resolution for CTD or underway variables (underway resolution is vessel-aware when cruise_name is given).

The nes-lter://stations and nes-lter://variable-aliases MCP resources provide stable reference context.

Plot viewer

web/nes-lter-vega-plot.js defines a reusable <nes-lter-vega-plot> browser component. The component accepts the vega_lite object returned by plot_ctd_profiles:

<script src="https://cdn.jsdelivr.net/npm/vega@5"></script>
<script src="https://cdn.jsdelivr.net/npm/vega-lite@5"></script>
<script src="https://cdn.jsdelivr.net/npm/vega-embed@6"></script>
<script type="module" src="./nes-lter-vega-plot.js"></script>
<nes-lter-vega-plot id="plot"></nes-lter-vega-plot>
<script>
  document.querySelector("#plot").spec = plot_result.vega_lite;
</script>

To view the included Spring 2025 L8 oxygen demonstration:

cd web
python3 -m http.server 8080

Open http://localhost:8080/demo.html. The nes-lter://vega-lite-viewer MCP resource exposes the component source to compatible clients.

Common variables include oxygen, temperature, salinity, density, fluorescence, and par. Raw CTD column names like sbox0mm_kg are also accepted.

By default, winter 2025 is interpreted meteorologically as Dec 2024 through Feb 2025.

Configuration

Set NES_LTER_API_BASE_URL to override the API base URL. Defaults to https://nes-lter-api.whoi.edu.

NES_LTER_CACHE_TTL controls the in-memory cache duration in seconds (default 900), and NES_LTER_MAX_CONCURRENCY controls concurrent API requests (default 8).

For efficient interaction, use query_ctd(..., include_points=false) first, then request full points for selected casts. For plots, prefer plot_ctd_profiles because it returns compact plotting data and a Vega-Lite spec. For maps, use GeoJSON from make_station_map or get_cruise_track_data. All data responses include source_url and retrieved_at.

Query benchmarks

benchmarks/bench_queries.py compares MCP tool latency with an equivalent direct NES-LTER API workflow. It records elapsed time, response size, row count, errors, median, and p95 summaries as JSON Lines:

uv run python benchmarks/bench_queries.py --warmups 2 --repetitions 10 --mode both --output benchmark-results.jsonl

Use --mode mcp or --mode direct to run one side only. Add --mode all for the optional bare-LLM comparison:

export LLM_API_KEY=...
export LLM_MODEL=gpt-4o-mini
export LLM_INPUT_USD_PER_1M=0
export LLM_OUTPUT_USD_PER_1M=0
uv run python benchmarks/bench_queries.py --mode all --repetitions 10 --output benchmark-results.jsonl

The bare-LLM condition receives only the API base URL and a few endpoint paths. The model produces an API plan without MCP tools, then the harness executes the allowlisted direct API workflow and returns the same profile rows. Its elapsed time therefore includes model planning plus API retrieval. LLM rows include total latency, separate model/API timings, token usage, and estimated cost when both pricing environment variables are set.

--mode all also includes a codex condition. It launches codex exec --json in an isolated temporary directory with user configuration, rules, and MCP settings excluded. Codex must retrieve the same structured data using read-only API requests. Use --codex-sandbox read-only by default; the Codex CLI must be installed and authenticated. Offline checks are in tests/test_bench_queries.py.

To plot multiple variables together, pass variables=["sbeox0ml_l", "t090c"]; the Vega-Lite result overlays them on one chart with a shared depth axis and independent x-scales, which avoids conflating their units. Use width and height to control the returned chart dimensions.