aicesat — cross-mission altimetry

An MCP server for Claude Desktop that pulls real ICESat-2 ATL03 photons and ICESat/GLAS GLAH06 shots over a chosen area, renders them as a 3D point cloud (deck.gl), and — on a toggle — applies an ITRF2014 + epoch co-registration (plate motion, ITRF2014-PMM / NOAM) with pyproj, updating the co-located Δh statistics. Started from docs/cross-mission-altimetry-mcp-spec.md, which carries the full design and rationale.

The co-registration removes plate motion between epochs. It does not remove ice flow, GIA, geoid/tide, firn compaction, or the vertical datum, and the widget says so on every answer. GLAS heights are converted TOPEX/Poseidon → WGS84 ellipsoid using the product's d_deltaEllip, with the saturation correction d_satElevCorr applied; that is recorded in every comparability block.

Setup

uv sync          # Python 3.13
uv run pytest    # offline unit tests

Earthdata Login: fetching NASA data needs a token; browsing the existing lake does not. The server resolves a token in this order: EARTHDATA_TOKEN (env) → a token file at ~/.edl/token.prod (override the path with AICESAT_EDL_FILE) → ~/.netrc. Generate a token at https://urs.earthdata.nasa.gov (User Profile → Generate Token). The server never writes to stdout (stdio MCP transport); logs go to stderr.

Related MCP server: mcp-opentopography

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json, using the absolute path to your checkout. Put your Earthdata token in the env block — this is machine-independent (no token file needed) and the recommended way for a new user to configure the server:

{
  "mcpServers": {
    "aicesat": {
      "command": "/opt/homebrew/bin/uv",
      "args": ["--directory", "/ABSOLUTE/PATH/TO/aicesat", "run", "aicesat-server"],
      "env": { "EARTHDATA_TOKEN": "<your Earthdata Login token>" }
    }
  }
}

If you keep your token in a file instead, drop the EARTHDATA_TOKEN line and either place it at ~/.edl/token.prod or add "AICESAT_EDL_FILE": "/path/to/your/token" to env. Restart Claude Desktop. The unified UI renders inline as an MCP App; the server also serves it at http://127.0.0.1:8765/ (port via AICESAT_PORT) for use in a browser.

Getting an Earthdata Login token (step by step)

1. Create a free Earthdata Login account if you don't have one: https://urs.earthdata.nasa.gov → Register.

2. Sign in, then open your profile (top-right) → the Generate Token tab → Generate Token. Copy the long token string (a JWT that starts with eyJ…). Tokens last ~60 days — regenerate when one stops working.

3. Paste it into the Claude Desktop config shown above, as the value of EARTHDATA_TOKEN in the server's env block. The config file is at ~/Library/Application Support/Claude/claude_desktop_config.json (in Claude Desktop: Settings → Developer → Edit Config).

4. Restart Claude Desktop. The Lake view works without a token; building a scene / checking coverage will now authenticate. If it can't, the UI shows an error banner naming what to fix.

A ~/.netrc with your Earthdata username/password also works, but a token in env is the most reliable and is what we recommend for sharing the server with a colleague.

Tools: survey_coverage, elevation_change and show_timeseries (the place-first ladder: coverage, change, one cell's record), open_ui, list_regions, list_scenes, check_coverage, show_photons (region, bbox, or polygon), add_glas, coregister, find_timeseries_candidates, lake_status, lake_load_cells, job_status. By default (the demo profile) only the three ladder tools are exposed, with the demo UI (how the UWG demo was recorded). AICESAT_PROFILE=full exposes every tool above and the full UI.

Asking for a time series

find_timeseries_candidates ranks the places in an already-built scene where an elevation time series can actually be measured, and show_timeseries shows one of them. Both open the Time series view inline.

The search bins every mission's points into H3 cells and fixed time windows, keeps cells seen in three or more windows, and fits one local reference plane per cell so surface slope is removed rather than mistaken for change. Each cell gets a deterministic 0–1 confidence dominated by within-cell roughness — the real failure mode, where two missions sample different sub-cell relief and fake a trend. why names the top two limiters in plain language.

The candidate list is summarised for the caller (no per-cell series, no geometry) and reports n_candidates_total alongside what it returned, so a truncated answer still says how much it left behind; the view shows every cell. trend_cm_yr is the least-squares rate through the window medians and is uncorrected for inter-campaign / inter-sensor bias and for GIA — quote it with that caveat, as params.notes states on every answer.

UI

One self-contained page (built from src/aicesat/ui/* + vendored deck.gl / h3-js by scripts/build_ui.py, pure Python; the server rebuilds it on start when sources change), served both inline in Claude Desktop and at /:

• Explore — a 3-D globe (Natural Earth basemap, no flat projection). Navigate anywhere, draw a box or polygon, check coverage, and build a scene as a background job; scene footprints and the loaded H3 cells are shown on the globe.

• Lake — the persistent Parquet lake as an H3 grid: per-cell stats on hover, a storage limit that auto-evicts the least-recently-used cells, and background loading or eviction of selected cells.

• Scene — the 3-D viewer: ICESat-2 and GLAS points draped on a DEM, an Adjustments panel of correction toggles, and the co-located Δh histograms. The true plate-motion shift is sub-pixel at scene scale, so the clouds do not visibly move — the effect is read from the Δh panel, not an exaggerated visual. Panels collapse and close.

• Time series (#ts/<scene_id>) — the same candidate list and chart the Scene panel carries, given the whole page and no 3-D. It needs only the scene metadata and one search call, so unlike the Scene view it renders completely inside Claude Desktop, where the point cloud's push stream cannot follow (tools/call is request/response). Selecting a different cell is a local redraw: the view already holds every candidate's series.

The UI talks to a transport-neutral API (api.py) exposed two ways: the localhost /api/* routes for the browser, and visibility:["app"] MCP tools the host proxies for the inline app. scripts/e2e_apps.py checks the MCP-App wiring.

Architecture

The ATL03 path does not open HDF5 at query time. Per granule, an index build (index.py) records each chunk's byte range, filter pipeline, and the H3 cells it touches. Queries resolve a bbox/polygon to cells, fetch only the needed chunks by HTTPS range request (EDL bearer token → presigned URL), decode them without an HDF5 library, and materialize photons into a hive-partitioned Parquet lake (lake.py) with per-row provenance and co-registered coordinates. DuckDB answers over the lake (api.py); a coverage table records what is materialized so repeat queries fetch nothing. The earlier earthaccess.open + h5py path is kept as atl03.extract_legacy for comparison. scripts/bench_access.py compares the access methods; see the spec (Appendix C) for the approach.

Scene geometry is latitude-aware (scene.frame_crs): polar-stereographic near the poles, a per-scene azimuthal-equidistant projection elsewhere, so scenes render anywhere on Earth.

DEM and imagery

The scene surface is a real DEM chosen by region, always on WGS84-ellipsoid heights (the same vertical reference as ATL03), read by window over /vsicurl/ and cached: ArcticDEM v4.1 (Arctic, EPSG:3413) and REMA v2.0 (Antarctic, EPSG:3031) — both already ellipsoidal — and Copernicus GLO-30 elsewhere, whose EGM2008 orthometric heights are converted to ellipsoidal by adding the NGA egm08 geoid undulation (h = H + N). There is no photon-interpolated fallback: a scene shows a DEM only where one covers it. Scene imagery is Sentinel-2 cloudless (EOX, CC BY-NC-SA 4.0), draped on the surface. The Explore/Lake globe basemap is Natural Earth 50 m land (public domain). Attributions appear on screen.

Scripts

uv run scripts/check_coverage.py --region egig_west_flank   # granule counts by month / laser campaign
uv run scripts/ingest.py egig_west_flank                    # index + byte-range ingest + lake query
uv run scripts/build_index.py --region egig_west_flank      # offline index pre-build (amortized off the query path)
uv run scripts/make_scene.py egig_west_flank --glas --coreg # full pipeline for a region
uv run scripts/serve.py                                     # widget server only, for local testing
uv run scripts/bench_access.py                              # access-method comparison

Data (data/) is gitignored; delete it to force a re-fetch.

How Δh is measured

For each GLAS shot, the ICESat-2 surface height at the footprint centre comes from a local along-track linear fit of the signal photons within the co-location radius. A disc median is an order statistic and cannot resolve the sub-cm slope effect; the fit is continuous in position, so it can. Only the along-beam component of the plate-motion shift is observable on a single beam, and the per-pair artifact panel keeps the mm-level vertical part of the frame step separate from the slope effect. Every answer carries the unresolved list and states "plate motion applied", never "the missions agree".