Skip to content
Developer

Developer guide

Build on the ocean

Ask about a place by name and get the whole answer in one call: tide times, conditions right now, sun and moon, and the best time to go. The same answers are a clean REST API and a hosted MCP server your AI can call, with an interactive tide chart in ChatGPT and Claude. Anonymous access works out of the box; a free key raises the limit 10×.

31 MCP tools18 documented operations3 NOAA APIs, one surfaceNo NOAA paperwork

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 “best time to go tidepooling near Half Moon Bay this week?” 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 31 tools

Five place-first tools answer most questions from a place name in one call and render an interactive card. The rest expose specific NOAA and National Weather Service products by station ID.

  • perigee_get_tidesHigh and low tides for up to a week, the water level right now, and sun and moon for each day.
  • perigee_get_conditionsTide state, observed wind and temperatures, the next 12 hours of wind, and active NWS alerts.
  • perigee_get_sun_moonSun, twilight, golden hour, moonrise, moonset, and phase for any coordinates worldwide.
  • perigee_find_best_timeRanked windows for eight coastal activities from tide, daylight, and forecast wind, with reasons.
  • perigee_find_stationsNOAA tide stations by name, state, or proximity.

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_prediction_offsets

Long-term products

  • noaa_get_sea_level_trends
  • noaa_get_sea_level_rise_projections
  • noaa_get_extreme_water_levels
  • noaa_get_top_ten_water_levels
  • noaa_get_high_tide_flooding

Sky

  • astro_get_moon_phase
  • astro_get_next_moon_phase
  • astro_get_sun_times
  • astro_get_sun_position
  • astro_get_next_sun_event

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/tides?place= | ?latitude=&longitude= | ?station_id= · &days=1..7
GET /api/v1/conditionsright now · tide, wind, temps, alerts
GET /api/v1/sun-moonworldwide · ?latitude= &longitude= &time_zone=
GET /api/v1/best-time?place= &activity=tidepooling|paddling|… &days=
GET /api/v1/placesplace, state, or coordinates → stations
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/tides?place=Santa%20Cruz,%20CA&days=3"

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