stofs-mcp

STOFS MCP Server

MCP server providing AI assistants with access to NOAA's Storm Tide Operational Forecast System (STOFS) — operational storm surge and water level forecasts, and validation against CO-OPS observations.

Status: Ready

Tools

Tool	Description
stofs_list_cycles	List available STOFS forecast cycles on AWS S3
stofs_get_station_forecast	Get water level forecast time series at a CO-OPS station
stofs_get_point_forecast	Get forecast at arbitrary lat/lon (nearest STOFS station)
stofs_get_gridded_forecast	Forecast at any lat/lon via OPeNDAP (regular grid, no download)
stofs_compare_with_observations	Compare STOFS forecast vs CO-OPS observations (bias, RMSE, correlation)
stofs_get_max_water_level	Get top stations by peak predicted water level in a cycle
stofs_get_system_info	STOFS model specifications, datums, cycle schedule
stofs_list_stations	List STOFS output stations, filter by state/region/proximity

STOFS Models

STOFS-2D-Global (ADCIRC)

• Domain: Global unstructured mesh (~12.8M nodes)
• Cycles: 4x daily — 00, 06, 12, 18 UTC
• Forecast: 180 hours (7.5 days)
• Stations: ~385 output points at 6-minute resolution
• Datum: LMSL (Local Mean Sea Level)
• Data: s3://noaa-gestofs-pds

STOFS-3D-Atlantic (SCHISM)

• Domain: US East Coast + Gulf of Mexico + Puerto Rico (~2.9M nodes)
• Cycles: 1x daily — 12 UTC
• Forecast: 96 hours (4 days)
• Stations: ~108 output points at 6-minute resolution
• Datum: NAVD88
• Data: s3://noaa-nos-stofs3d-pds

Vertical Datums

⚠️ Datum differences matter when comparing models and observations:

• STOFS-2D station files: LMSL (Local Mean Sea Level)
• STOFS-3D station files: NAVD88
• CO-OPS API: Use datum=MSL for 2D comparison, datum=NAVD for 3D comparison
• Small systematic offsets (1–5 cm) between LMSL and MSL are expected

Quick Start

git clone https://github.com/mansurjisan/ocean-mcp.git
cd ocean-mcp/servers/stofs-mcp
uv sync

Configure your MCP client

{
  "mcpServers": {
    "stofs": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ocean-mcp/servers/stofs-mcp", "python", "-m", "stofs_mcp"]
    }
  }
}

Example Queries

• "What is the latest STOFS-2D-Global forecast cycle?"
• "Get the water level forecast for The Battery, NY (station 8518750)"
• "Compare STOFS forecast vs observations at Boston for the past 24 hours"
• "Find STOFS stations within 50 km of New Orleans"
• "What are the top 10 stations with highest predicted water levels?"
• "Get the surge-only forecast at Charleston, SC"
• "Show me the STOFS forecast near lat 29.95, lon -90.07"
• "Get the STOFS forecast at lat 36.85, lon -75.98 (Virginia Beach) using the gridded product"

Running Tests

# Unit tests (fast, no network)
uv run pytest tests/test_utils.py -v

# Live integration tests (requires internet, downloads ~5–10 MB)
uv run pytest tests/test_live.py -v -s

Data Sources

• AWS S3 (primary): noaa-gestofs-pds (2D-Global), noaa-nos-stofs3d-pds (3D-Atlantic)
• NOMADS OPeNDAP: nomads.ncep.noaa.gov/dods/stofs_2d_glo/ (remote slice of regular-grid data, ~2-day window)
• CO-OPS API: api.tidesandcurrents.noaa.gov (for observation validation)

License

MIT