@cyanheads/noaa-marine-mcp-server

Public Hosted Server: https://noaa-marine.caseyjhand.com/mcp

Tools

Seven tools covering the full US marine operational workflow — station discovery, tide predictions, observed water levels, tidal current predictions and profiles, and live offshore buoy conditions:

noaa_marine_find_stations

Unified station discovery across CO-OPS (3,450+ tide/water-level stations, 4,430+ current stations) and NDBC (1,354+ active buoys worldwide).

• Filter by proximity (latitude/longitude + radius), name substring, state/territory, source (CO-OPS vs NDBC), or types: data capabilities (tide, current, water_level, met, current_profile) or NDBC platform class (buoy)

• Returns a unified station list with source, coordinates, distance, data capabilities, and — for NDBC — the physical platform class (buoy, fixed, oilrig, dart, tao, usv, other)

• Station lists are cached in-memory (6-hour TTL) — first call after startup may be slightly slower

• Required first step: CO-OPS and NDBC use non-overlapping ID systems; guessing a station ID reliably fails

noaa_marine_get_tide_predictions

CO-OPS MLLW tide predictions for planning tidal windows.

• High/low events (default) or 6-minute continuous curve

• Eight datums: MLLW (default, US nautical chart), MHHW, MSL, MTL, MHW, MLW, CD, STND

• Time zone options: local standard/daylight (default), GMT, local standard only

• Units: English (feet, default) or metric (meters)

• Maximum date range: 1 year per request (typed error date_range_exceeded for longer ranges)

noaa_marine_get_water_level

Observed water level vs. predicted — the storm surge view.

• 6-minute observed water level readings with quality flags

• Paired tide predictions fetched in parallel (failure degrades gracefully — observed levels still returned)

• Optional residual summary: max surge and max drawdown when both series are present

• Maximum date range: 31 days per request for 6-minute data

noaa_marine_get_currents

CO-OPS tidal current predictions for passage planning.

• MAX_SLACK interval (default): max flood, max ebb, and slack events only — the actionable view for transiting inlets and channels

• 6-minute interval: full continuous current curve for charting or integration

• Current station IDs use alphanumeric format (e.g., ACT4176), distinct from numeric tide station IDs — use find_stations with types: ["current"] to discover them

noaa_marine_get_conditions

Live NDBC buoy observations (most recent ~45 days, updated every 10 minutes).

• Wave height (m), dominant and average period (sec), mean wave direction

• Wind speed and gust (m/s), wind direction

• Sea-surface temperature, air temperature, dew point (°C)

• Barometric pressure (hPa)

• All sensor fields nullable (null when buoy sensor did not report — normal for offshore buoys)

• All values in SI units except TIDE (feet) and VIS (nautical miles), which are rarely populated at offshore buoys

noaa_marine_get_current_profile

Observed ocean-current depth profile from an NDBC ADCP buoy — the most recent measurement at each depth bin.

• Depth (m), direction (degrees true, the direction the current flows toward), and speed (cm/s) per bin

• Distinct from noaa_marine_get_currents: this is an NDBC observed acoustic-Doppler measurement, not a CO-OPS tidal-current prediction

• Most NDBC stations serve no ADCP profile — use find_stations with source="ndbc" and types: ["current_profile"] to discover the ones that do

• Direction or speed is null for a bin when NDBC did not report that component

noaa_marine_get_ocean_observations

Sub-surface water-column observations from an NDBC station — the most recent reading at each reported depth.

• Water temperature (°C), conductivity (mS/cm), salinity (psu), dissolved oxygen (% saturation and ppm), chlorophyll (µg/l), turbidity (FTU), pH, and redox potential (mV) per depth

• The water-column counterpart to noaa_marine_get_conditions: this reports what the water is doing below the surface, that one reports surface weather and sea state

• Sensor coverage is sparse — most stations report only temperature and salinity; any value the station did not report comes back null, never a fabricated zero

• Sub-surface sensors are on only a subset of NDBC stations and carry no station-catalog flag, so there is no capability filter — call it on candidate source="ndbc" station IDs and expect the observations_not_found error on the many stations that serve no ocean file

Related MCP server: mcp-noaa-tides

Resources and prompts

All resource data is also reachable via tools. Use noaa_marine_find_stations to discover station IDs before accessing the resource.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool and resource definitions — single file per primitive, framework handles registration and validation

• Unified error handling — handlers throw, framework catches, classifies, and formats with typed error contracts

• Structured logging with optional OpenTelemetry tracing

• STDIO and Streamable HTTP transports

• Pluggable auth: none, jwt, oauth

NOAA-specific:

• In-memory station cache (6-hour TTL) for CO-OPS and NDBC station lists — discovery is fast after first startup

• CO-OPS and NDBC integrated in a unified station model — find_stations fans out across both sources in parallel

• NDBC fixed-width text parser: MM (missing sensor data) normalized to null, not passed through as strings

• Paired water-level + prediction fetches for storm surge residual computation

• CO-OPS application= courtesy parameter sent on every request (configurable via NOAA_APPLICATION_ID)

Agent-friendly output:

• Datum echoed on every tide/water-level response — agents can state units and reference correctly without assumptions

• total_found on find_stations shows count before limit slice so agents know whether to re-query

• All NDBC sensor fields explicitly nullable with per-field unit documentation — agents don't fabricate missing readings

• Typed station source (coops | ndbc) on every station record, plus a data-capability type and (NDBC only) a platform class where applicable — agents can branch on data, not string parsing

Getting started

No API key required. Both NOAA CO-OPS and NDBC are open, keyless data sources.

Public Hosted Instance

Connect directly via Streamable HTTP — no install, no API key:

{
  "mcpServers": {
    "noaa-marine": {
      "type": "streamable-http",
      "url": "https://noaa-marine.caseyjhand.com/mcp"
    }
  }
}

Self-hosted / local

Add the following to your MCP client configuration file:

{
  "mcpServers": {
    "noaa-marine": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/noaa-marine-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "noaa-marine": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/noaa-marine-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "noaa-marine": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/noaa-marine-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3.14 or higher (or Node.js v24+).

• No external API keys needed — NOAA CO-OPS and NDBC are fully open.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/noaa-marine-mcp-server.git

2. Navigate into the directory:

cd noaa-marine-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# edit .env if needed (all vars optional)

Configuration

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  bun run rebuild
  
  bun run start:stdio
  # or
  bun run start:http

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t noaa-marine-mcp-server .
docker run --rm -p 3010:3010 noaa-marine-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/noaa-marine-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md/AGENTS.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic

• Use ctx.log for request-scoped logging

• Register tools and resources in src/index.ts directly (no barrels for this server)

• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

• NDBC MM values must normalize to null, not be passed through as strings

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.