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×.
Give your AI the tides
One hosted endpoint — https://perigeetides.com/mcp — speaking MCP streamable HTTP. Pick your client:
- Run this in your terminal — that's the whole setup:
claude mcp add --transport http perigee https://perigeetides.com/mcpOpen 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/conditions | right now · tide, wind, temps, alerts |
| GET /api/v1/sun-moon | worldwide · ?latitude= &longitude= &time_zone= |
| GET /api/v1/best-time | ?place= &activity=tidepooling|paddling|… &days= |
| GET /api/v1/places | place, state, or coordinates → stations |
| GET /api/v1/stations | directory · ?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-levels | observed · ?hours= &datum= |
| GET /api/v1/stations/{id}/conditions | latest water level, wind, temps, pressure |
| GET /api/v1/stations/{id}/forecast | NWS wind forecast + coastal waters text · ?hours= &units= |
| GET /api/v1/astronomy | ?lat= &lon= [&date= &days=] |
| POST /api/v1/decisions/trip-health | public explainable planning sample |
| POST /api/v1/decisions/best-window | rank 2–12 candidate windows · Pro |
| POST /api/v1/decisions/evaluate-rules | deterministic decision rules · Pro |
| POST /api/v1/decisions/material-change | compare prior and current inputs · Pro |
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.
npm install perigee-tidespython -m pip install perigeeRate limits & keys
| Tier | Limit | Monthly | Identified by |
|---|---|---|---|
| Anonymous | 30 req/min | — | client IP |
| Free key | 300 req/min | 10,000 | Authorization: Bearer pg_live_… |
| Pro key | 3,000 req/min | 250,000 | Authorization: Bearer pg_live_… |
- MCP and REST have separate buckets, so heavy scripting never starves your AI session.
- Every response carries
X-RateLimit-*andX-Quota-Month-*headers; a 429 includesRetry-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: Bearerorx-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 mcp add noaa -- npx -y @ryancardin/noaa-tides-currents-mcp-server