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 referenceMCP guideOpenAPI 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

Open the full MCP guide, registry identity, and source trail.

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. Before mixing a prediction with a gauge reading, review how NOAA tide predictions, datums, and source freshness work, then use the versioned station coverage audit when you need the exact fail-closed availability method and downloads.

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/mcp as 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