NOAA Tides and Currents

🌊 NOAA 潮汐与洋流 MCP 服务

---

快速开始

# Run immediately with npx
npx @ryancardin/noaa-tides-currents-mcp-server

# Or the short alias
npx noaa-mcp

Claude Desktop / Claude Code 配置

{
  "mcpServers": {
    "noaa": {
      "command": "npx",
      "args": ["-y", "@ryancardin/noaa-tides-currents-mcp-server"]
    }
  }
}

Claude Code 单行命令：

claude mcp add noaa -- npx -y @ryancardin/noaa-tides-currents-mcp-server

HTTP 模式（可选）

npx noaa-mcp --http --port 3000   # stateless streamable HTTP at http://localhost:3000/mcp

无需 API 密钥 — NOAA 的 CO-OPS API 开放使用。

---

工具（25 个）

观测与预测（Data API）

工具	功能
noaa_get_water_levels	观测水位：1 分钟、6 分钟或每小时序列；解码初步/已验证质量标记
noaa_get_water_level_summaries	high_low（每日极值 HH/H/L/LL）、daily_mean（五大湖）、daily_max_min、monthly_mean 基准面表
noaa_get_tide_predictions	调和潮汐预测 — hilo 高潮/低潮事件（最长 10 年）或间隔序列
noaa_get_currents	按深度分层观测洋流速度/方向（ADCP），可选波束诊断信息
noaa_get_current_predictions	洋流预测 — max_slack 涨潮/落潮/憩流事件或间隔序列
noaa_get_meteorological_data	风、气温/水温、气压、桥下净空、导电率、能见度、湿度、盐度

测站发现与元数据（Metadata API）

工具	功能
noaa_search_stations	按功能类型、名称子串和州搜索测站目录 — 支持分页
noaa_find_nearest_stations	查找距任意经纬度最近的测站（大圆距离，使用缓存目录），可按类型筛选
noaa_get_station_info	完整测站记录，包含可展开的传感器、洪水水位、基准点、分层、部署信息等
noaa_get_station_datums	潮汐基准面高程（MLLW、MSL、MHHW、NAVD88 等）、HAT/LAT、历史极值、当前或已被取代的时段
noaa_get_harmonic_constituents	测站预测所依据的 M2/S2/K1/... 分潮（水位或洋流椭圆形式）
noaa_get_prediction_offsets	从属测站相对于参考测站的时间/高度偏移量（潮汐或洋流）

气候与衍生产品（DPAPI）

工具	功能
noaa_get_sea_level_trends	长期相对海平面趋势，附误差范围和观测时段
noaa_get_sea_level_rise_projections	2022 年跨部门海平面上升情景预测，按年代划分，覆盖至 2150 年
noaa_get_extreme_water_levels	年超越概率水位（例如“百年一遇”水位）
noaa_get_top_ten_water_levels	有记录以来的最高水位及其成因事件（飓风、东北风暴）
noaa_get_high_tide_flooding	HTF 洪水日统计（按日/月/季/年）、展望、十年预测、发生概率

天文学（本地计算）

工具	功能说明
astro_get_moon_phase	查询某个日期或日期范围内的月相、照明比例、月龄和距离（春潮／小潮背景）
astro_get_next_moon_phase	查询下一个新月／满月／上弦月或下弦月的日期
astro_get_sun_times	查询任意地点和日期的日出／日落、曙暮光、黄金时段和日照时长
astro_get_sun_position	查询方位角／高度角（以及大致的赤纬／赤经）
astro_get_next_sun_event	查询任意太阳事件的下一次发生时间

风况与海洋预报（NWS Weather API）

工具	功能说明
nws_get_wind_forecast	查询美国任意纬度／经度的逐小时数值风力预报（风速／阵风／风向；有网格数据时还包括波高），最长约 7 天
nws_get_marine_forecast	查询覆盖某个纬度／经度的海洋分区官方沿海水域预报文本，包括小型船舶警报

参考资料

工具	功能说明
noaa_get_reference_guide	精选的 NOAA 参考资料：产品、基准面、单位、时区、间隔、站点类型、数据限制、质量标记、日期格式和海洋预报

每个工具都支持 response_format: "markdown"（含明确标注单位的易读表格，默认格式）或 "json"（完整的结构化负载），并附带供能使用这些内容的 MCP 客户端使用的结构化内容。

资源

• noaa://guide/getting-started — 工作流示例和常见问题
• noaa://reference/{topic} — 上述 10 个参考主题，可固定为资源

提示词

• tide_report — 指定地点／站点和日期的潮汐报告
• boating_conditions — 出发前简报：潮汐、海流、风况和日照
• station_flood_risk — 洪水风险概况：HTF 历史记录、极值、趋势和预测
• station_overview — 站点提供的所有信息

---

细节之处（已为你处理）

以下是 NOAA API 中容易出错的地方，本服务已处理这些问题：

• 基准面很重要。 没有垂直参考基准的高度毫无意义。默认使用 MLLW（海图基准面）；不同站点支持的基准面各不相同（五大湖使用 IGLD/LWD，没有潮汐预测）。noaa_get_station_datums 会提供基准面转换表。
• 单位并不对称。 metric 表示风速单位为 m/s，但海流速度单位为 cm/s；气压单位为毫巴，盐度单位为 PSU，且在两种单位系统中都相同。每条响应都会标明单位。
• 每种产品都有请求时间跨度限制（例如，1 分钟数据为 4 天、6 分钟数据为 31 天、逐小时数据为 1 年、hilo 预测为 10 年……）。请求发送给 NOAA 前，客户端会进行验证，并给出可执行的提示。
• 有两种站点 ID 方案。 水位／气象站使用 7 位数字（9414290）；海流站使用字母数字组合（cb0102）。
• 基准站与附属站。 附属（S）预测站仅支持 hilo 预测，其数据根据基准（R）站的偏移量推算得出。
• daily_mean 要求使用当地标准时间，且仅适用于五大湖站点；系统会自动强制执行此要求。
• 质量标记已解码。 行内会说明初步数据与验证数据的区别、sigma、标记字母（初步数据与验证数据使用的标记字母不同），以及 HH/H/L/LL 潮汐类型。
• 预测基于天文数据——不包含风暴潮；请与观测水位进行比较。
• 站点目录已缓存（6 小时），因此搜索最近站点时不会重新获取数千条记录。

---

使用示例

“明天波士顿的高潮时间是什么时候？”

1. noaa_find_nearest_stations（类型 tidepredictions）→ 8443970 BOSTON
2. noaa_get_tide_predictions（间隔 hilo）→ 高潮/低潮时间及高于 MLLW 的高度

“今天下午科德角运河的水流会有多强？”

1. noaa_find_nearest_stations（类型 currentpredictions）
2. noaa_get_current_predictions（间隔 max_slack）→ 最大涨潮/落潮流速（节）及憩流时间

“普罗维登斯现在和 20 年前相比，发生洪水的频率如何？预计 2050 年会怎样？”

1. noaa_get_high_tide_flooding（报告 annual，范围 25）
2. noaa_get_high_tide_flooding（报告 projections，年代 2050）
3. noaa_get_sea_level_trends + noaa_get_sea_level_rise_projections

---

开发

npm install
npm run build        # tsc → dist/
npm test             # vitest unit tests (validation, formatting, astronomy)
npm run test:live    # end-to-end smoke test against the live NOAA API
npm run inspector    # MCP Inspector against dist/index.js
npm run dev          # tsx src/index.ts

架构

src/
├── index.ts            # entry point: stdio (default) or --http streamable HTTP
├── constants.ts        # API base URLs, timeouts, cache TTLs, response limits
├── client/             # shared HTTP layer (retry/backoff, error mapping) + TTL cache
├── validation/         # date normalization + per-product span limit enforcement
├── format/             # unit labeling, flag legends, markdown/json response shaping
├── schemas/            # shared Zod field schemas with nuance-carrying descriptions
├── services/           # Data API, Metadata API, DPAPI, moon & sun services
├── tools/              # 25 tool registrations grouped by domain
├── resources/          # noaa:// reference resources
├── prompts/            # workflow prompt templates
└── reference/          # curated NOAA reference content

数据来源：

• 数据 API — api.tidesandcurrents.noaa.gov/api/prod/datagetter
• 元数据 API — api.tidesandcurrents.noaa.gov/mdapi/prod/webapi
• 衍生产品 API — api.tidesandcurrents.noaa.gov/dpapi/prod/webapi
• 天文计算 — suncalc，在本地计算

许可证

MIT © Cardin LLC（Cardin Labs）

NOAA 数据由 NOAA 海洋学产品与服务业务中心（CO-OPS）提供。本项目与 NOAA 无关，也未获得 NOAA 的认可。

2.1.0 工具交付规范

每个原始工具都会声明输出架构。成功的服务提供方响应会保留其字段，并添加 _response: { contractVersion: "2026-09-29.1", status: "complete" }。参考指南使用单独的、带类型的主题/指南结果。文本和结构化载荷都有大小限制：超出大小的结果会返回明确的 response_too_large 错误及缩小范围的指导，而不是返回被截断的文本，同时附带不受大小限制的结构化响应。错误元数据会说明重试是否可能有效。串联的服务提供方读取共享 45 秒的取消期限，每个请求的总重试时限为 18 秒。不会根据原始数据推断捕鱼、航行或捕获概率。