Perigee Tides MCP Server

🌊 NOAA Tides & Currents MCP Server

A Model Context Protocol server for NOAA CO-OPS Tides and Currents data

Built by Cardin Labs · Hosted at Perigee

Water levels · tide predictions · currents · marine weather · station metadata · tidal datums · harmonic constituents · sea level trends & projections · high tide flooding · sun & moon calculations

---

Quick Start

# Run immediately with npx
npx @ryancardin/noaa-tides-currents-mcp-server

# Or the short alias
npx noaa-mcp

Claude Desktop / Claude Code configuration

{
  "mcpServers": {
    "noaa": {
      "command": "npx",
      "args": ["-y", "@ryancardin/noaa-tides-currents-mcp-server"]
    }
  }
}

Claude Code one-liner:

claude mcp add noaa -- npx -y @ryancardin/noaa-tides-currents-mcp-server

HTTP mode (optional)

npx noaa-mcp --http --port 3000   # stateless streamable HTTP at http://localhost:3000/mcp

No API key is required — NOAA's CO-OPS APIs are open.

---

Tools (25)

Observations & Predictions (Data API)

Station Discovery & Metadata (Metadata API)

Climate & Derived Products (DPAPI)

Astronomy (computed locally)

Wind & Marine Forecasts (NWS Weather API)

Reference

Every tool supports response_format: "markdown" (readable tables with units spelled out — the default) or "json" (complete structured payload), and attaches structured content for MCP clients that consume it.

Resources

• noaa://guide/getting-started — workflow recipes and common pitfalls
• noaa://reference/{topic} — the ten reference topics above as pinnable resources

Prompts

• tide_report — tide report for a place/station and date
• boating_conditions — pre-departure briefing: tides, currents, wind, daylight
• station_flood_risk — flood risk profile: HTF history, extremes, trends, projections
• station_overview — everything a station offers

---

The Nuances (handled for you)

These are the things that make NOAA's API tricky — this server encodes them:

• Datums matter. Heights are meaningless without a vertical reference. MLLW (chart datum) is the default; stations differ in which datums they support (Great Lakes use IGLD/LWD and have no tide predictions). noaa_get_station_datums gives the conversion table.
• Units are asymmetric. metric means m/s for wind but cm/s for currents; air pressure is millibars and salinity PSU in both systems. Every response labels its units.
• Per-product request-span limits (4 days for 1-minute data, 31 days for 6-minute, 1 year hourly, 10 years for hilo predictions...) are validated client-side with actionable messages before hitting NOAA.
• Two station ID schemes. Water-level/met stations are 7-digit numeric (9414290); current stations are alphanumeric (cb0102).
• Reference vs subordinate stations. Subordinate (S) prediction stations only support hilo predictions, derived by offsets from a reference (R) station.
• daily_mean requires local standard time and only exists for Great Lakes stations — enforced automatically.
• Quality flags decoded. Preliminary vs verified data, sigma, flag alphabets (which differ between preliminary and verified!), and HH/H/L/LL tide types are explained inline.
• Predictions are astronomical — storm surge is not included; compare with observed water levels.
• Station directory is cached (6 h) so nearest-station searches don't refetch thousands of records.

---

Usage Examples

"When is high tide in Boston tomorrow?"

1. noaa_find_nearest_stations (type tidepredictions) → 8443970 BOSTON
2. noaa_get_tide_predictions (interval hilo) → high/low times & heights above MLLW

"How strong will the current be in the Cape Cod Canal this afternoon?"

1. noaa_find_nearest_stations (type currentpredictions)
2. noaa_get_current_predictions (interval max_slack) → max flood/ebb (knots) and slack times

"How often does Providence flood now vs 20 years ago, and what's projected for 2050?"

1. noaa_get_high_tide_flooding (report annual, range 25)
2. noaa_get_high_tide_flooding (report projections, decade 2050)
3. noaa_get_sea_level_trends + noaa_get_sea_level_rise_projections

---

Development

npm install
npm run build        # tsc → dist/
npm test             # vitest unit tests (validation, formatting, astronomy)
npm run test:live    # end-to-end smoke test against the live NOAA API
npm run inspector    # MCP Inspector against dist/index.js
npm run dev          # tsx src/index.ts

Architecture

src/
├── index.ts            # entry point: stdio (default) or --http streamable HTTP
├── constants.ts        # API base URLs, timeouts, cache TTLs, response limits
├── client/             # shared HTTP layer (retry/backoff, error mapping) + TTL cache
├── validation/         # date normalization + per-product span limit enforcement
├── format/             # unit labeling, flag legends, markdown/json response shaping
├── schemas/            # shared Zod field schemas with nuance-carrying descriptions
├── services/           # Data API, Metadata API, DPAPI, moon & sun services
├── tools/              # 25 tool registrations grouped by domain
├── resources/          # noaa:// reference resources
├── prompts/            # workflow prompt templates
└── reference/          # curated NOAA reference content

Data sources:

• Data API — api.tidesandcurrents.noaa.gov/api/prod/datagetter
• Metadata API — api.tidesandcurrents.noaa.gov/mdapi/prod/webapi
• Derived Product API — api.tidesandcurrents.noaa.gov/dpapi/prod/webapi
• Astronomy — suncalc, computed locally

License

MIT © Cardin LLC (Cardin Labs)

NOAA data is provided by the NOAA Center for Operational Oceanographic Products and Services (CO-OPS). This project is not affiliated with or endorsed by NOAA.