.codex-plugin— mcp server

<div align="center"> <h1>@cyanheads/noaa-marine-mcp-server</h1> <p><b>Find NOAA tide stations and NDBC buoys, fetch tide predictions, water levels, tidal currents, and live buoy conditions via MCP. STDIO or Streamable HTTP.</b> <div>5 Tools • 1 Resource</div> </p> </div>

<div align="center">

</div>

<div align="center">

</div>

<div align="center">

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

</div>

Tools

Five tools covering the full US marine operational workflow — station discovery, tide predictions, observed water levels, tidal current predictions, 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 type (tide, current, water_level, buoy, met)
• Returns unified station list with source, type, capabilities, coordinates, and distance
• 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

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) and type fields on every station record — 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.11 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

1. Navigate into the directory:

cd noaa-marine-mcp-server

1. Install dependencies:

bun install

1. 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.