noaa-marine-mcp-server

---

概述

通过 NOAA CO-OPS 和 NDBC 获取美国潮汐、潮流、水位和浮标观测数据。查找沿海站点和浮标，然后获取潮汐和潮流预报、观测水位和月平均水位，以及实时浮标状况、流速剖面和水柱读数。

工具

工具	描述
noaa_marine_find_stations	按位置、名称、ID、州或能力查找 CO-OPS 潮汐、水位和潮流站点，以及 NDBC 浮标
noaa_marine_get_tide_predictions	获取 CO-OPS 潮汐站的高潮/低潮预报或 6 分钟曲线
noaa_marine_get_water_level	获取四种时间间隔的观测水位，并附带预报和风暴潮残差
noaa_marine_get_monthly_means	获取 CO-OPS 水位站经核实的月度潮汐基准面和极值
noaa_marine_get_currents	获取 CO-OPS 潮流预报：最大涨潮流、最大落潮流和平潮事件，或 6 分钟曲线
noaa_marine_get_conditions	获取 NDBC 浮标实时状况：海浪、风、海表温度、气温和气压
noaa_marine_get_current_profile	获取 NDBC ADCP 浮标观测到的海流深度剖面
noaa_marine_get_ocean_observations	获取 NDBC 站点的次表层水柱读数（温度、盐度、氧气等）

资源

资源	描述
noaa-marine://station/{station_id}	CO-OPS 或 NDBC 站点的元数据：名称、坐标、来源、能力、预测类别、平台

除 NDBC 的 owner 外，资源中的所有信息也会出现在 noaa_marine_find_stations 的结果行中，供只调用工具的客户端使用。

能力参考

noaa_marine_find_stations _工具

• 筛选条件可组合使用：latitude 和 longitude 搭配 radius_km（默认值为 100，最大值为 1000）；query（在两个来源中按名称或 ID 子字符串匹配；如果按距离排序，精确 ID 匹配会优先）；state（仅 CO-OPS）；source（coops / ndbc / all）；以及 types（tide、current、water_level、met、current_profile、water_quality，或平台类别 buoy）；limit 默认值为 20，最大值为 200
• 每个站点都包含 source、capabilities、type；NDBC 站点还包含 platform。CO-OPS 结果行会添加 state（如果借用 25 km 内最近的、带有州信息的站点，则 state_derived: true）、潮汐 prediction_class（reference，或带有 reference_id 的 subordinate），以及洋流 bins[]，其中列出每个分层的编号、深度（英尺）和类别
• total_found 和 truncated 报告应用 limit 前的数量；无匹配项时仍为成功，并包含 applied_search；目录读取不完整时会在 sources 中标记；目录完全不可用时会返回 sources_unavailable；仅提供 latitude 或 longitude 时会返回 incomplete_coordinates

---

noaa_marine_get_tide_predictions _工具

• interval 可设为 hilo（默认值）或 6min，最长 365 天；十种基准面（MLLW、MHHW、MHW、MTL、MSL、MLW、DTL、NAVD、STND、CRD）、time_zone（lst_ldt、gmt、lst）和 units（english 英尺、metric 米）
• 6min 仅适用于基准站：从属站点会以 subordinate_no_6min 失败，并指出其基准站；五大湖站点会返回 no_predictions，并指向 noaa_marine_get_water_level
• 其他失败情况：invalid_date_range、date_range_exceeded、station_not_found、datum_unavailable（列出站点所具有的基准面）以及 upstream_throttled（可重试的 CO-OPS HTTP 403，几分钟后会解除）

---

noaa_marine_get_water_level _工具

• interval 可设为 6min（默认值，31 天）、hourly 或 high_low（365 天），或 daily_mean（3,655 天，仅限五大湖，始终使用 LST；沿海站点会返回 great_lakes_only）；十三种基准面（MLLW、MHHW、MHW、MTL、MSL、MLW、NAVD、STND、IGLD、LWD、CRD、LWI、HWI）
• 观测数据包含 quality（p / v，仅限 6min）、sigma（6min 和 hourly）以及 type（H / HH / L / LL，仅限 high_low）；没有读数的时间段会被丢弃，并计入 gaps_dropped
• 会提供匹配间隔的配对预测（daily_mean 除外），并通过 predictions_status（empty / unavailable）说明序列为空的原因；residual_summary（max_surge、max_drawdown）涵盖整个匹配范围，仅适用于 6min 和 hourly。失败情况：invalid_date_range、date_range_exceeded、station_not_found、datum_unavailable、no_data、verified_data_lag（较粗时间间隔的数据窗口结束于上个月第一天或之后；CO-OPS 可能尚未完成验证）以及 upstream_throttled

---

noaa_marine_get_monthly_means _工具

• 每次请求最多 73,000 天；支持十一个基准面（MLLW、MHHW、MHW、MTL、MSL、MLW、NAVD、STND、IGLD、LWD、CRD），单位为 english 英尺或 metric 米；返回的首尾月份分别是 begin_date 和 end_date 所属的月份
• 每月一行：highest、lowest、潮汐基准面（mhhw、mhw、msl、mtl、mlw、mllw、dtl）、潮差（gt、mn、dhq、dlq）、以小时为单位的月潮间隔（hwi、lwi），以及原样返回的 inferred 代码；CO-OPS 留空的值会被省略，因此五大湖站点只包含 highest、msl 和 lowest
• 错误：invalid_date_range、date_range_exceeded、station_not_found、datum_unavailable、upstream_throttled；对于空时间窗口，如果结束日期为上个月 1 日或之后，则返回 verified_data_lag，否则返回 no_data

---

noaa_marine_get_currents _工具

• interval 为 MAX_SLACK（默认值：最大涨潮、最大落潮和憩流事件）或 6min，最多 365 天；bin 从 bins[] 中选择深度层（默认为最浅层）；units 为 english（节、英尺）或 metric（厘米/秒、米）
• 每个响应都会回显 bin 和 depth；各行包含 flood / ebb / slack 类型、非负的 speed，以及作为 direction 返回的该站点此类水流的平均方位
• 如果站点没有请求的深度层，则返回 bin_unavailable 并列出可用深度层；CO-OPS 不预测事件的站点会返回空列表，并在 notice 中附上说明；没有已发布预测的站点则返回 predictions_unavailable；还可能返回 invalid_date_range、date_range_exceeded、station_not_found、no_predictions 和 upstream_throttled

---

noaa_marine_get_conditions _工具

• 一个 NDBC station_id；返回风、波浪、海表温度、气温、露点和气压，单位为 SI 制，但 tide_ft 和 visibility_nmi 除外
• 每个传感器字段都可为空；每个数据列块取自 90 分钟内最新的、包含该数据的行。波浪数据会报告自己的 waves_observed_at，其他较早的数据块则会在 notice 中注明。错误：buoy_not_found、no_sensor_data

---

noaa_marine_get_current_profile _工具

• 一个通过 types: ["current_profile"] 查找的 NDBC station_id；bins[] 按深度从浅到深排列，包含 depth_m、direction_deg（真北基准、流向）和 speed_cm_s；后两项在未报告时为 null
• 返回观测到的 ADCP 测量数据，而非 noaa_marine_get_currents 返回的 CO-OPS 预测数据；错误为 profile_not_found（没有 ADCP 文件）和 no_current_data

---

noaa_marine_get_ocean_observations _工具

• 一个通过 types: ["water_quality"] 查找的 NDBC station_id；这是目录标记，不代表一定有数据；readings[] 按深度包含行，字段包括温度、电导率、盐度、溶解氧（% 和 ppm）、叶绿素、浊度、pH 和氧化还原电位
• 大多数站点只报告温度和盐度，未报告的值为 null；错误为 observations_not_found（没有 .ocean 文件）和 no_ocean_data

---

noaa-marine://station/{station_id} _资源

• station_id 来自 noaa_marine_find_stations；以 application/json 格式返回该工具的站点记录；对于 NDBC 站点，还包含 owner，并带有 6 小时的 cacheHint
• 仅在已读取两个目录后才会返回 station_not_found；若其中一个目录无法读取，则返回 source_unavailable

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），并提供结构化日志和可选的 OpenTelemetry 跟踪。

CO-OPS / NDBC 专属功能：

• CO-OPS 数据和元数据 API，以及 NDBC 活跃站点目录和 realtime2 数据流（.txt、.adcp、.ocean）；站点目录在内存中缓存 6 小时；CO-OPS 请求会通过 NOAA_APPLICATION_ID 传递 application=
• 站点 ID 不会跨数据源混用：CO-OPS 潮汐和水位 ID 为数字（9447130），CO-OPS 海流 ID 为字母数字组合（ACT4176），NDBC ID 为 5 位代码（46041）
• CO-OPS 工具接受格式为 YYYYMMDD 或 YYYY-MM-DD 的 begin_date / end_date，并在调用前检查日期是否有效以及各工具的范围上限（invalid_date_range、date_range_exceeded）；水位默认使用 MLLW，若站点不支持指定基准面，则会返回 datum_unavailable 并列出该站点支持的基准面
• CO-OPS 每月会针对前一个月验证 hourly、high_low、daily_mean 和月平均值：如果空数据窗口结束时间在前一个月 1 日或之后，则返回 verified_data_lag；更早的窗口则返回 no_data
• CO-OPS 在短时间内收到大量请求时，会持续约两分钟返回 HTTP 403；CO-OPS 数据工具会将其报告为可重试的 upstream_throttled，并在恢复信息中说明等待时长

便于 Agent 使用的输出：

• 四种 CO-OPS 时间序列工具支持按字节数限制分页：适合单页的数据范围会完整返回；较长的数据范围则返回开头一页，并附带 rows_matched、rows_returned、page_offset 和 next_offset，使用 offset 翻页（limit 会缩小页面）
• 缺失值会表示为 null 或省略，绝不会伪造：NDBC 的 MM 标记会变为 null，CO-OPS 的空值会被丢弃，quality 不会被设置默认值，而是直接省略
• 使用带有明确类型的字段：站点 source（coops | ndbc）、能力 type、NDBC platform 和 prediction_class；每个 CO-OPS 水位响应都会附带基准面和单位，方便调用方根据数据而非字符串解析来分支处理

快速开始

公共托管实例

公共实例位于 https://noaa-marine.caseyjhand.com/mcp，无需安装或 API 密钥。该实例使用 Streamable HTTP；每个客户端都有各自的配置格式。

对于 Claude Code：

claude mcp add --transport http noaa-marine-mcp-server https://noaa-marine.caseyjhand.com/mcp

对于 Cline（cline_mcp_settings.json）：

{
  "mcpServers": {
    "noaa-marine-mcp-server": {
      "type": "streamableHttp",
      "url": "https://noaa-marine.caseyjhand.com/mcp"
    }
  }
}

对于 Cursor（mcp.json）：

{
  "mcpServers": {
    "noaa-marine-mcp-server": {
      "url": "https://noaa-marine.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop 可在 Settings → Connectors 下添加远程服务。

自托管 / 本地

将以下内容添加到 MCP 客户端配置文件中：

{
  "mcpServers": {
    "noaa-marine-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/noaa-marine-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或者使用 npx（无需 Bun）：

{
  "mcpServers": {
    "noaa-marine-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/noaa-marine-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或者使用 Docker：

{
  "mcpServers": {
    "noaa-marine-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/noaa-marine-mcp-server:latest"
      ]
    }
  }
}

要使用 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥：NOAA CO-OPS 和 NDBC 都是开放数据源。

安装

1. 克隆代码库：

git clone https://github.com/cyanheads/noaa-marine-mcp-server.git

2. 进入目录：

cd noaa-marine-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env if needed (all vars optional)

配置

变量	描述	默认值
NOAA_APPLICATION_ID	作为 application= 随 CO-OPS 请求发送的标识符。	noaa-marine-mcp-server
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_HTTP_HOST	HTTP 绑定地址。	127.0.0.1
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。	stateless
MCP_AUTH_MODE	身份验证：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
LOGS_DIR	日志文件目录（仅 Node.js）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败工具调用的参数和结果（仅按键名脱敏），并受 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES 限制。	false
OTEL_ENABLED	启用 OpenTelemetry。	false
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP 基础 URL；跟踪和指标会导出到其下的 /v1/traces 和 /v1/metrics。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	用于选择性启用 OTLP 日志导出的端点；基础 URL 本身不会启用日志导出。	—

完整的可选覆盖项列表请参阅 .env.example。

运行服务端

本地开发

• 构建并运行：

  bun run rebuild
  
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t noaa-marine-mcp-server .
docker run --rm -p 3010:3010 noaa-marine-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/noaa-marine-mcp-server。默认会安装 OpenTelemetry 对等依赖——构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖。

项目结构

路径	用途
src/index.ts	createApp() 入口：注册工具和资源，并初始化服务。
src/config/	使用 Zod 解析 NOAA_APPLICATION_ID 环境变量。
src/services/coops/	CO-OPS 客户端：站点目录缓存、数据获取、错误分类、日期范围验证、行分页和州解析。
src/services/ndbc/	NDBC 服务：活动站点 XML 和 realtime2 数据流解析器。
src/services/geo.ts	用于邻近搜索和州解析的 Haversine 距离计算。
src/mcp-server/tools/definitions/	八个工具定义（*.tool.ts）。
src/mcp-server/resources/definitions/	站点元数据资源（noaa-marine-station.resource.ts）。
tests/	与 src/ 对应的 Vitest 测试。
docs/	设计文档和目录树。

开发指南

开发指南和架构规则请参阅 CLAUDE.md/AGENTS.md。简要内容如下：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志
• 直接在 src/index.ts 中注册工具和资源（本服务不使用汇总导出文件）
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段
• NDBC 的 MM 值必须规范化为 null，不能作为字符串原样传递

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。