{
  "markdown": "# 🌊 NOAA Tides & Currents MCP Server\n\n<div align=\"center\">\n\n[![npm version](https://img.shields.io/npm/v/@ryancardin/noaa-tides-currents-mcp-server?style=for-the-badge&logo=npm&color=blue)](https://www.npmjs.com/package/@ryancardin/noaa-tides-currents-mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n[![MCP](https://img.shields.io/badge/MCP-Model_Context_Protocol-green?style=for-the-badge)](https://modelcontextprotocol.io/)\n\n**A Model Context Protocol server for NOAA CO-OPS Tides and Currents data**\n\nBuilt by [Cardin Labs](https://cardinlabs.com) · Hosted at [Perigee](https://perigee-two.vercel.app)\n\nWater levels · tide predictions · currents · marine weather · station metadata ·\ntidal datums · harmonic constituents · sea level trends & projections ·\nhigh tide flooding · sun & moon calculations\n\n</div>\n\n---\n\n## Quick Start\n\n```bash\n# Run immediately with npx\nnpx @ryancardin/noaa-tides-currents-mcp-server\n\n# Or the short alias\nnpx noaa-mcp\n```\n\n### Claude Desktop / Claude Code configuration\n\n```json\n{\n  \"mcpServers\": {\n    \"noaa\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ryancardin/noaa-tides-currents-mcp-server\"]\n    }\n  }\n}\n```\n\nClaude Code one-liner:\n\n```bash\nclaude mcp add noaa -- npx -y @ryancardin/noaa-tides-currents-mcp-server\n```\n\n### HTTP mode (optional)\n\n```bash\nnpx noaa-mcp --http --port 3000   # stateless streamable HTTP at http://localhost:3000/mcp\n```\n\nNo API key is required — NOAA's CO-OPS APIs are open.\n\n---\n\n## Tools (25)\n\n### Observations & Predictions (Data API)\n\n| Tool | What it does |\n|---|---|\n| `noaa_get_water_levels` | Observed water levels: 1-minute, 6-minute, or hourly series, preliminary/verified quality flags decoded |\n| `noaa_get_water_level_summaries` | high_low (HH/H/L/LL daily extremes), daily_mean (Great Lakes), daily_max_min, monthly_mean datum tables |\n| `noaa_get_tide_predictions` | Harmonic tide predictions — `hilo` high/low events (up to 10 years) or interval series |\n| `noaa_get_currents` | Observed current speed/direction by depth bin (ADCP), optional beam diagnostics |\n| `noaa_get_current_predictions` | Predicted currents — `max_slack` flood/ebb/slack events or interval series |\n| `noaa_get_meteorological_data` | Wind, air/water temperature, pressure, air gap (bridge clearance), conductivity, visibility, humidity, salinity |\n\n### Station Discovery & Metadata (Metadata API)\n\n| Tool | What it does |\n|---|---|\n| `noaa_search_stations` | Search the station directory by capability type, name substring, state — paginated |\n| `noaa_find_nearest_stations` | Nearest stations to any lat/lon (great-circle, cached directory), filterable by type |\n| `noaa_get_station_info` | Full station record with expandable sensors, flood levels, benchmarks, bins, deployments... |\n| `noaa_get_station_datums` | Tidal datum elevations (MLLW, MSL, MHHW, NAVD88...), HAT/LAT, historic extremes, current or superseded epoch |\n| `noaa_get_harmonic_constituents` | The M2/S2/K1/... constituents behind a station's predictions (water level or current ellipse form) |\n| `noaa_get_prediction_offsets` | Subordinate-station time/height offsets from their reference stations (tide or current) |\n\n### Climate & Derived Products (DPAPI)\n\n| Tool | What it does |\n|---|---|\n| `noaa_get_sea_level_trends` | Long-term relative sea level trend with error bars and observation period |\n| `noaa_get_sea_level_rise_projections` | 2022 Interagency SLR scenario projections per decade through 2150 |\n| `noaa_get_extreme_water_levels` | Annual exceedance probability levels (e.g. the \"100-year\" water level) |\n| `noaa_get_top_ten_water_levels` | Highest water levels ever recorded, with causal events (hurricanes, nor'easters) |\n| `noaa_get_high_tide_flooding` | HTF flood-day counts (daily/monthly/seasonal/annual), outlooks, decadal projections, likelihoods |\n\n### Astronomy (computed locally)\n\n| Tool | What it does |\n|---|---|\n| `astro_get_moon_phase` | Phase, illumination, age, distance for a date or range (spring/neap tide context) |\n| `astro_get_next_moon_phase` | Next new/full/quarter moon date(s) |\n| `astro_get_sun_times` | Sunrise/sunset, twilights, golden hour, day length for any location/date |\n| `astro_get_sun_position` | Azimuth/altitude (+ approximate declination/RA) |\n| `astro_get_next_sun_event` | Next occurrence(s) of any sun event |\n\n### Wind & Marine Forecasts (NWS Weather API)\n\n| Tool | What it does |\n|---|---|\n| `nws_get_wind_forecast` | Hourly numeric wind forecast (speed/gust/direction, wave height where gridded) for any US lat/lon, up to ~7 days |\n| `nws_get_marine_forecast` | Official Coastal Waters Forecast narrative for the marine zone covering a lat/lon, incl. Small Craft Advisories |\n\n### Reference\n\n| Tool | What it does |\n|---|---|\n| `noaa_get_reference_guide` | Curated NOAA reference: products, datums, units, time zones, intervals, station types, data limits, quality flags, date formats, marine forecasts |\n\nEvery 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.\n\n## Resources\n\n- `noaa://guide/getting-started` — workflow recipes and common pitfalls\n- `noaa://reference/{topic}` — the ten reference topics above as pinnable resources\n\n## Prompts\n\n- `tide_report` — tide report for a place/station and date\n- `boating_conditions` — pre-departure briefing: tides, currents, wind, daylight\n- `station_flood_risk` — flood risk profile: HTF history, extremes, trends, projections\n- `station_overview` — everything a station offers\n\n---\n\n## The Nuances (handled for you)\n\nThese are the things that make NOAA's API tricky — this server encodes them:\n\n- **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.\n- **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.\n- **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.\n- **Two station ID schemes.** Water-level/met stations are 7-digit numeric (`9414290`); current stations are alphanumeric (`cb0102`).\n- **Reference vs subordinate stations.** Subordinate (S) prediction stations only support `hilo` predictions, derived by offsets from a reference (R) station.\n- **`daily_mean` requires local standard time** and only exists for Great Lakes stations — enforced automatically.\n- **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.\n- **Predictions are astronomical** — storm surge is not included; compare with observed water levels.\n- **Station directory is cached** (6 h) so nearest-station searches don't refetch thousands of records.\n\n---\n\n## Usage Examples\n\n> \"When is high tide in Boston tomorrow?\"\n\n1. `noaa_find_nearest_stations` (type `tidepredictions`) → `8443970 BOSTON`\n2. `noaa_get_tide_predictions` (interval `hilo`) → high/low times & heights above MLLW\n\n> \"How strong will the current be in the Cape Cod Canal this afternoon?\"\n\n1. `noaa_find_nearest_stations` (type `currentpredictions`)\n2. `noaa_get_current_predictions` (interval `max_slack`) → max flood/ebb (knots) and slack times\n\n> \"How often does Providence flood now vs 20 years ago, and what's projected for 2050?\"\n\n1. `noaa_get_high_tide_flooding` (report `annual`, range 25)\n2. `noaa_get_high_tide_flooding` (report `projections`, decade 2050)\n3. `noaa_get_sea_level_trends` + `noaa_get_sea_level_rise_projections`\n\n---\n\n## Development\n\n```bash\nnpm install\nnpm run build        # tsc → dist/\nnpm test             # vitest unit tests (validation, formatting, astronomy)\nnpm run test:live    # end-to-end smoke test against the live NOAA API\nnpm run inspector    # MCP Inspector against dist/index.js\nnpm run dev          # tsx src/index.ts\n```\n\n### Architecture\n\n```\nsrc/\n├── index.ts            # entry point: stdio (default) or --http streamable HTTP\n├── constants.ts        # API base URLs, timeouts, cache TTLs, response limits\n├── client/             # shared HTTP layer (retry/backoff, error mapping) + TTL cache\n├── validation/         # date normalization + per-product span limit enforcement\n├── format/             # unit labeling, flag legends, markdown/json response shaping\n├── schemas/            # shared Zod field schemas with nuance-carrying descriptions\n├── services/           # Data API, Metadata API, DPAPI, moon & sun services\n├── tools/              # 25 tool registrations grouped by domain\n├── resources/          # noaa:// reference resources\n├── prompts/            # workflow prompt templates\n└── reference/          # curated NOAA reference content\n```\n\nData sources:\n- **Data API** — `api.tidesandcurrents.noaa.gov/api/prod/datagetter`\n- **Metadata API** — `api.tidesandcurrents.noaa.gov/mdapi/prod/webapi`\n- **Derived Product API** — `api.tidesandcurrents.noaa.gov/dpapi/prod/webapi`\n- **Astronomy** — [suncalc](https://github.com/mourner/suncalc), computed locally\n\n## License\n\nMIT © [Cardin LLC](https://cardinlabs.com) (Cardin Labs)\n\nNOAA 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.\n",
  "bytes": 9853,
  "sha": "1b13add54bbf54e08965ee23b7436e0d1e730045d4586e3ab7886759b16e9887",
  "repo_slug": "ryancardin15/perigee-tides",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ryancardin15_noaa_tides_and_cu_a03c4abf/readme"
}