USGS Water Services MCP Server

OceanMCP

一个包含多个可独立安装的 MCP 服务的单体仓库，用于海洋和沿海数据工作流。

服务

服务	PyPI	描述
coops-mcp		NOAA CO-OPS 潮汐、水位、洋流和气象数据
erddap-mcp		通过 80 多个公共服务器访问各类 ERDDAP 数据
nhc-mcp		NHC 风暴路径、公告和 HURDAT2 最佳路径数据
recon-mcp		飓风侦察数据（HDOB、涡旋数据消息、ATCF 定位数据）
stofs-mcp		NOAA STOFS 风暴潮预报和观测验证
ofs-mcp		NOAA OFS 区域海洋模型预报（水位、温度、盐度）
rtofs-mcp		通过 HYCOM THREDDS 获取 NOAA RTOFS 全球海洋预报（SST、盐度、洋流、SSH）
ww3-mcp		GFS-Wave（WAVEWATCH III）预报和 NDBC 浮标波浪观测
ndbc-mcp		NOAA NDBC 浮标观测——波浪、SST、风、气压（1,300 多个站点）
winds-mcp		来自 ASOS / AWOS 站点的 NWS 地面风观测
usgs-mcp		USGS 水务服务——流量、NWS/NWPS 洪水状态、洪峰事件
goes-mcp		NOAA GOES-18/19 卫星图像——可见光、红外、水汽
adcirc-mcp		ADCIRC 模型设置调试、参数查询和配置验证
schism-mcp		SCHISM 模型设置调试、参数查询和配置验证

数据服务无需 API 密钥——以上所有服务均使用免费公开的数据集。例外是 hpc-system-mcp 和 ufs-runner-mcp（见下文），它们需要实际访问 NOAA RDHPCS 集群；其中 ufs-runner-mcp 还会提交真实的 Slurm 作业。

此仓库中还有其他服务尚未发布到 PyPI（请从源代码安装）：vdatum-mcp（垂直基准面转换）、hpc-system-mcp 和 ufs-runner-mcp（NOAA RDHPCS / UFS-Coastal HPC 工作流——需要集群访问权限），以及 alert-mcp（CO-OPS 阈值告警）。

此仓库中还有第 19 个服务 nos-workflow-mcp，它仍处于实验阶段，尚在开发中（其完整实现位于一个尚未合并的分支上——main 分支仅包含最小子集）。因此，它特意未列入上表，目前也尚不适合一般使用。

快速开始

从 PyPI 安装

# uvx (recommended) — runs without permanent install, like npx for Python
uvx coops-mcp

# pip — install into current environment
pip install coops-mcp

# pipx — install in isolated environment with CLI entry point
pipx install coops-mcp

将 coops-mcp 替换为任意已发布的服务：erddap-mcp、nhc-mcp、recon-mcp、stofs-mcp、ofs-mcp、rtofs-mcp、ww3-mcp、ndbc-mcp、winds-mcp、usgs-mcp、goes-mcp、adcirc-mcp、schism-mcp。

从源代码安装

git clone https://github.com/oceanmodeling/ocean-mcp.git
cd ocean-mcp/servers/coops-mcp  # or any other server directory under servers/
uv sync

配置 MCP 客户端

添加到 MCP 设置中（例如，项目 .mcp.json）：

使用 PyPI 软件包（推荐）：

{
  "mcpServers": {
    "coops": {
      "command": "uvx",
      "args": ["coops-mcp"]
    },
    "erddap": {
      "command": "uvx",
      "args": ["erddap-mcp"]
    },
    "nhc": {
      "command": "uvx",
      "args": ["nhc-mcp"]
    },
    "recon": {
      "command": "uvx",
      "args": ["recon-mcp"]
    },
    "stofs": {
      "command": "uvx",
      "args": ["stofs-mcp"]
    },
    "ofs": {
      "command": "uvx",
      "args": ["ofs-mcp"]
    },
    "rtofs": {
      "command": "uvx",
      "args": ["rtofs-mcp"]
    },
    "ww3": {
      "command": "uvx",
      "args": ["ww3-mcp"]
    }
  }
}

{
  "mcpServers": {
    "coops": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ocean-mcp/servers/coops-mcp", "python", "-m", "coops_mcp"]
    },
    "erddap": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ocean-mcp/servers/erddap-mcp", "python", "-m", "erddap_mcp"]
    },
    "nhc": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ocean-mcp/servers/nhc-mcp", "python", "-m", "nhc_mcp"]
    },
    "recon": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ocean-mcp/servers/recon-mcp", "python", "-m", "recon_mcp"]
    },
    "stofs": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ocean-mcp/servers/stofs-mcp", "python", "-m", "stofs_mcp"]
    },
    "ofs": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ocean-mcp/servers/ofs-mcp", "python", "-m", "ofs_mcp"]
    },
    "rtofs": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ocean-mcp/servers/rtofs-mcp", "python", "-m", "rtofs_mcp"]
    },
    "ww3": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ocean-mcp/servers/ww3-mcp", "python", "-m", "ww3_mcp"]
    }
  }
}

示例查询

配置好服务后，你可以用自然语言向 AI 助手提问：

CO-OPS 查询：

• “获取纽约州 The Battery 的当前水位”
• “查找 Miami Beach 附近的潮汐站”
• “南卡罗来纳州 Charleston 的洪水统计数据是什么？”
• “显示旧金山的海平面趋势”

ERDDAP 查询：

• “在 CoastWatch 上搜索海表温度数据集”
• “获取 2024 年 1 月加利福尼亚海岸附近的叶绿素数据”
• “美国东海岸有哪些 ERDDAP 服务？”
• “列出 IOOS Gliders ERDDAP 上的所有滑翔机数据集”

NHC 查询：

• “目前有没有活跃的热带气旋？”
• “显示卡特里娜飓风的路径”
• “搜索大西洋上的 5 级飓风”
• “活跃风暴的预报路径是什么？”

Recon 查询：

• “列出 2024 年大西洋季的 HDOB 侦察飞行”
• “获取 2024 年 10 月 7 日的 HDOB 飞行高度观测数据”
• “显示飓风 Milton 的涡旋数据消息”
• “获取风暴 AL14 2024 的 ATCF 飞机定位数据”

STOFS 查询：

• “获取纽约州 The Battery 的 STOFS 水位预报”
• “比较过去 24 小时 Boston 的 STOFS 预报与观测数据”
• “预测水位最高的站点有哪些？”
• “查找 New Orleans 周围 50 km 内的 STOFS 站点”

OFS 查询：

• “哪些 OFS 模型覆盖 Chesapeake Bay？”
• “获取 CBOFS 在纬度 38.98、经度 -76.48 处的水位预报”
• “比较 CBOFS 水位与站点 8571892 的 CO-OPS 观测数据”
• “列出今天可用的 NGOFS2 预报周期”

RTOFS 查询：

• “获取 RTOFS 在北纬 40°、西经 74°处的海表温度预报”
• “显示 Gulf Stream 的温度深度剖面”
• “HYCOM THREDDS 上目前有哪些 RTOFS 数据集可用？”
• “获取从 Miami 到 Bermuda 的盐度垂直剖面”
• “显示 Gulf of Mexico 的 SST 区域预报”

WW3 查询：

• “有哪些 GFS-Wave 模型网格可用？”
• “查找 Cape Hatteras 附近的 NDBC 浮标”
• “获取浮标 41025 的最新波浪观测数据”
• “显示未来 48 小时北纬 35°、西经 75°处的 GFS-Wave 预报”
• “比较波浪预报与浮标 41025 的观测数据”

跨服务查询：

• “查找这个 ERDDAP 浮标位置附近的 CO-OPS 站点”
• “比较潮汐站数据与附近 ERDDAP 卫星 SST 数据”
• “是否有活跃飓风威胁 Gulf Coast？如果有，请显示 New Orleans 的 STOFS 风暴潮预报”
• “获取 Chesapeake Bay 的 CBOFS 水位预报，并与同一站点的 CO-OPS 潮汐预测进行比较”
• “显示 ERDDAP 中 The Battery 附近的海表温度，以及 CO-OPS 的当前水位”
• “历史上哪些 NHC 风暴袭击过 Gulf Coast？显示受影响站点的 CO-OPS 洪水统计数据”
• “获取同一位置的 STOFS 网格预报和 OFS 水位预报，并进行比较”

架构

每个服务都完全独立，拥有自己的 pyproject.toml、依赖项和测试。有关共享约定的详情，请参阅 docs/architecture.md。

各服务共用的模式：

• 使用 FastMCP 作为 MCP 服务框架
• 使用 httpx 作为异步 HTTP 客户端
• 使用 Pydantic 模型，并通过 Literal[...] 类型约束参数
• 默认提供只读工具——数据获取服务只获取数据，绝不修改任何内容。ufs-runner-mcp（提交/取消 Slurm 作业）和 alert-mcp（创建/暂停/删除内存中的警报状态）是两个例外，各自有少量标记为 readOnlyHint=False 的工具
• 根据工具不同，response_format 输出格式为 markdown（默认）、json、geojson 或 image
• 提供包含建议的可操作错误消息

有关完整的响应/行为约定（输出上限、retrieved_at、错误格式、HTTP 重试、依赖项版本范围），请参阅 CONVENTIONS.md。

引用

如果您在研究或工作中使用本项目，请引用：

@software{jisan2025oceanmcp,
  author    = {Jisan, Mansur Ali},
  title     = {Ocean MCP: Real-Time Marine Data, MCP-Native},
  year      = {2025},
  url       = {https://github.com/oceanmodeling/ocean-mcp},
  note      = {MCP servers for NOAA CO-OPS, ERDDAP, NHC, Recon, STOFS, OFS, RTOFS, WW3, NDBC, USGS, winds, GOES, ADCIRC, and SCHISM data}
}

许可证

本软件采用 MIT 许可证。您可以根据 MIT 条款使用、修改和分发本软件。详情请参阅 LICENSE。