Skip to content
Developer

Developer guide

Build on the ocean

Everything Perigee shows — live water levels, tide predictions, currents, weather at the gauge, and the sky above it — is yours as a clean REST API and a hosted MCP server your AI can call. Anonymous access works out of the box; a free key raises the limit 10×.

26 MCP tools13 documented operations3 NOAA APIs, one surfaceNo NOAA paperwork
Open playgroundAPI referenceOpenAPI 3.1

Give your AI the tides

One hosted endpoint — https://perigeetides.com/mcp — speaking MCP streamable HTTP. Pick your client:

  1. Run this in your terminal — that's the whole setup:
terminal
claude mcp add --transport http perigee https://perigeetides.com/mcp

Then ask things like “when is the next high tide in Seattle?” or “compare current speed at cb0102 over the last two days.” Want your account's limits? Clients with a sign-in flow (claude.ai, Claude Desktop) just connect to /pro/mcp and approve the Perigee prompt — no key handling at all. Clients that send headers can keep using an API key as Authorization: Bearer on either URL.

The 26 tools

Water

  • noaa_get_water_levels
  • noaa_get_water_level_summaries
  • noaa_get_tide_predictions
  • noaa_get_currents
  • noaa_get_current_predictions

Weather

  • noaa_get_meteorological_data
  • nws_get_wind_forecast
  • nws_get_marine_forecast

Stations

  • noaa_search_stations
  • noaa_find_nearest_stations
  • noaa_get_station_info
  • noaa_get_station_datums
  • noaa_get_harmonic_constituents
  • noaa_get_tide_prediction_offsets
  • noaa_get_station_sensors
  • noaa_get_current_station_bins
  • noaa_get_station_flood_levels

Derived products

  • noaa_get_sea_level_trends
  • noaa_get_extreme_water_levels
  • noaa_get_high_tide_flooding
  • noaa_get_top_ten_water_levels

Sky

  • astro_get_moon_phase
  • astro_get_sun_times
  • astro_get_sun_position

Reference

  • noaa_get_reference_guide
  • perigee_whoami

The server also exposes reference topics as MCP resources (noaa://reference/…) and prompt templates for tide reports and fishing windows.

REST API

The site itself runs on these endpoints — anything the pages show, you can fetch.

GET /api/v1/stationsdirectory · ?q= ?type= ?state=
GET /api/v1/stations/nearest?lat= &lon= [&type=]
GET /api/v1/stations/{id}metadata, datums, flood levels
GET /api/v1/stations/{id}/predictions?interval=hilo|6|60 &hours= &datum=
GET /api/v1/stations/{id}/water-levelsobserved · ?hours= &datum=
GET /api/v1/stations/{id}/conditionslatest water level, wind, temps, pressure
GET /api/v1/stations/{id}/forecastNWS wind forecast + coastal waters text · ?hours= &units=
GET /api/v1/astronomy?lat= &lon= [&date= &days=]
POST /api/v1/decisions/trip-healthpublic explainable planning sample
POST /api/v1/decisions/best-windowrank 2–12 candidate windows · Pro
POST /api/v1/decisions/evaluate-rulesdeterministic decision rules · Pro
POST /api/v1/decisions/material-changecompare prior and current inputs · Pro
example
curl "https://perigeetides.com/api/v1/stations/9414290/predictions?interval=hilo&hours=48"

Official SDKs

The JavaScript and Python clients share the versioned API contract, return request and quota metadata, and have no runtime dependencies. Public tide calls work without a key; keep credentials on your server for authenticated decision calls.

JavaScript / TypeScript
npm install perigee-tides
Python
python -m pip install perigee

Rate limits & keys

TierLimitMonthlyIdentified by
Anonymous30 req/min—client IP
Free key300 req/min10,000Authorization: Bearer pg_live_…
Pro key3,000 req/min250,000Authorization: Bearer pg_live_…
  • MCP and REST have separate buckets, so heavy scripting never starves your AI session.
  • Every response carries X-RateLimit-* and X-Quota-Month-* headers; a 429 includes Retry-After. Commercial quota reservation fails closed instead of silently granting overage.
  • Connecting from claude.ai or Claude Desktop? Add /pro/mcpas the connector URL and sign in when prompted — the OAuth connection carries your tier, so there's no key to paste (connector UIs don't accept one anyway).
  • Keys are shown once at creation, stored hashed, and revocable any time in the dashboard. Send them as Authorization: Bearer or x-api-key.
  • Tiers and what they cost live on the pricing page.

Prefer to self-host?

The underlying MCP server is open source and runs over stdio for local use:

Claude Code (local stdio)
claude mcp add noaa -- npx -y @ryancardin/noaa-tides-currents-mcp-server