NOAA TidesAndCurrents MCP

🚀 美国国家海洋和大气管理局（NOAA）潮汐与海流MCP服务器

本项目借助MCP协议，为用户提供闪电般快速的NOAA海洋与大气数据访问能力。用户可通过它一站式获取潮汐、海流、天气、天文和气候等丰富数据。

🚀 快速开始

⚡ NPX安装（推荐）

# 立即安装并运行，无需额外设置！
npx @ryancardin/noaa-tides-currents-mcp-server

# 或者使用更简短的别名
npx noaa-mcp

🔌 传输模式

• STDIO模式（默认 - MCP协议）

# 用于Claude桌面集成的标准MCP服务器
npx @ryancardin/noaa-tides-currents-mcp-server

# 或者使用更简短的别名
npx noaa-mcp

• HTTP可流式模式（用于Web集成）

# 在默认端口3000上启动HTTP服务器
npx @ryancardin/noaa-tides-currents-mcp-server --http

# 指定自定义端口
npx @ryancardin/noaa-tides-currents-mcp-server --http --port 8080

# 使用更简短的别名
npx noaa-mcp --http --port 8080

# 通过服务器发送事件（SSE）访问
curl http://localhost:3000/sse

🎯 Claude桌面集成

可通过Smithery直接安装到Claude桌面：

npx -y @smithery/cli install @RyanCardin15/tidesandcurrents --client claude

🔧 手动开发设置

# 克隆并构建项目
git clone https://github.com/RyanCardin15/NOAA-Tides-And-Currents-MCP.git
cd NOAA-Tides-And-Currents-MCP
npm install && npm run build

# 启动服务器
npm start

# 使用FastMCP进行测试
npx fastmcp dev dist/index.js

✨ 主要特性

• 🌊 25+专业工具：涵盖从基础潮汐数据到高级气候预测等多种功能。
• ⚡ 闪电般快速：基于FastMCP构建，性能卓越。
• 🎯 零配置：可直接与Claude桌面配合使用。
• 🌍 全面的数据：包含水位、海流、天气、月相、太阳数据等。
• 📊 适用于气候研究：提供海平面趋势、洪水预测、极端事件等数据。
• 🚀 支持NPX：通过单条命令即可完成安装和运行。

🛠️ 可用工具

🌊 水数据工具（6个工具）

水位与潮汐

• get_water_levels：获取实时和历史水位数据。
• get_tide_predictions：获取高低潮预测和连续数据。
• get_currents：获取实时和历史海流测量数据。
• get_current_predictions：获取海流速度和方向预测。
• get_meteorological_data：获取风、气温、水温、气压等气象数据。

站点信息

• get_stations：搜索和列出监测站点。
• get_station_details：获取站点详细元数据和功能信息。

🔬 气候与研究工具（9个工具）

海平面分析

• get_sea_level_trends：获取长期海平面上升趋势和速率。
• get_extreme_water_levels：对极端事件进行统计分析。

高潮洪水分析

• get_high_tide_flooding_daily：获取每日洪水事件计数。
• get_high_tide_flooding_monthly：获取每月洪水模式。
• get_high_tide_flooding_seasonal：进行季节性洪水分析。
• get_high_tide_flooding_annual：获取年度洪水趋势。
• get_high_tide_flooding_projections：获取未来洪水风险情景。
• get_high_tide_flooding_likelihoods：获取每日洪水概率。

历史极值

• get_top_ten_water_levels：获取有记录以来的最高/最低水位。

🌙 天文工具（7个工具）

月相计算

• get_moon_phase：获取当前月相和光照情况。
• get_moon_phases_range：获取指定日期范围内的月相。
• get_next_moon_phase：查找下一个新月/满月/季度月。

太阳计算

• get_sun_times：获取日出、日落、黎明、黄昏时间。
• get_sun_times_range：获取指定日期范围内的太阳时间。
• get_sun_position：获取实时太阳方位角和仰角。
• get_next_sun_event：获取下一个日出、日落或太阳正午时间。

⚙️ 配置工具（1个工具）

API参数

• get_parameter_definitions：获取所有API参数的有效取值。

💻 使用示例

🌊 获取当前潮汐状况

# 获取波士顿港的最新水位
get_water_levels station="8443970" date="latest"

# 获取迈阿密今天的潮汐预测
get_tide_predictions station="8723214" begin_date="today" end_date="today" interval="hilo"

🌀 飓风准备

# 获取极端水位统计数据，用于风暴规划
get_extreme_water_levels station="8518750" units="english"

# 检查明天的洪水可能性
get_high_tide_flooding_likelihoods station="8518750" date="2024-12-16" threshold="minor"

🔬 气候研究

# 分析30年的海平面趋势
get_sea_level_trends station="8518750" affiliation="US"

# 获取2050年代在中等海平面上升情景下的高潮洪水预测
get_high_tide_flooding_projections station="8518750" scenario="intermediate" decade="2050s"

🌙 天文与导航

# 获取今晚用于导航的月相
get_moon_phase date="2024-12-15" latitude="42.3601" longitude="-71.0589"

# 计算帆船航行的日出/日落时间
get_sun_times date="2024-12-15" latitude="25.7617" longitude="-80.1918" timezone="America/New_York"

🎣 钓鱼与休闲

# 根据当前预测获取最佳钓鱼时间
get_current_predictions station="ACT0446" date="today" interval="MAX_SLACK"

# 获取风和天气状况
get_meteorological_data station="8443970" product="wind" date="today"

🏗️ 高级用法

🔧 开发与测试

# 在开发模式下运行（stdio）
npm run dev

# 使用HTTP传输进行开发
npm run dev:http

# 使用不同的传输方式进行生产构建
npm start                    # STDIO模式（默认）
npm run start:http          # 在端口3000上启动HTTP服务
npm run start:http:3001     # 在端口3001上启动HTTP服务
npm run start:http:8080     # 在端口8080上启动HTTP服务

# 检查服务器功能
npx fastmcp inspect dist/index.js

🌐 HTTP流集成

当以HTTP模式运行时，服务器在/sse提供服务器发送事件（SSE）：

# 启动HTTP服务器
npx @ryancardin/noaa-tides-currents-mcp-server --http --port 3000

# 测试端点
curl -N http://localhost:3000/sse

# 或者与Web应用集成
fetch('http://localhost:3000/sse')
  .then(response => response.body.getReader())
  .then(reader => {
    // 处理流式MCP响应
  });

HTTP模式的使用场景

• 🌐 Web应用：可与React、Vue、Angular等应用集成。
• 📱 移动应用：为移动应用提供类似REST的访问方式。
• 🔗 API网关：可通过负载均衡器或API网关进行代理。
• 🧪 测试：便于使用curl进行测试和调试。

📊 数据格式与导出

所有工具支持多种输出格式：

• JSON（默认）：非常适合编程使用。
• XML：可用于与旧系统集成。
• CSV：可直接导入电子表格。

🌍 全球站点覆盖

• 13000+站点：遍布全球。
• 实时数据：来自NOAA的CO - OPS网络。
• 历史记录：可追溯到数十年前。
• 全球潮汐预测和海流预报。

🚦 API端点

本服务器集成了三个NOAA API：

🔧 技术细节

架构

• 🚀 FastMCP框架：高性能MCP服务器。
• 📝 TypeScript：提供完整的类型安全和智能提示。
• 🔧 Zod验证：进行运行时参数验证。
• ⚡ Axios HTTP客户端：实现可靠的API通信。
• 🌙 SunCalc集成：进行精确的天文计算。

传输选项

• 📡 STDIO传输：适用于桌面客户端的标准MCP协议。
• 🌐 HTTP流传输：通过服务器发送事件实现Web集成。
• 🔄 双模式支持：可通过命令行标志在不同传输方式之间切换。

系统要求

• Node.js 18+
• NPM 8+
• MCP客户端（如Claude桌面等）

包大小

• 📦 打包后：43.9 KB
• 📂 安装后：286.2 KB
• ⚡ 加载时间：<100ms

🐛 故障排除

常见问题及解决方案

服务器无法启动

# 检查Node.js版本
node --version  # 应大于等于18

# 重新构建TypeScript
npm run build

API错误

• 无效的站点ID：使用get_stations查找有效的站点。
• 日期格式问题：使用YYYYMMDD或MM/DD/YYYY格式。
• 速率限制：NOAA API有使用限制，请合理安排请求。

MCP连接问题

• 确保Claude桌面的MCP设置配置正确。
• 检查服务器二进制文件是否有执行权限：chmod +x dist/index.js

📈 路线图

• [ ] 🌊 实时警报：支持通过Webhook发送潮汐/天气警报。
• [ ] 📱 移动SDK：实现与React Native的集成。
• [ ] 🗺️ GIS集成：支持Shapefile和KML导出。
• [ ] 🤖 AI洞察：实现自动模式识别。
• [ ] ⚡ GraphQL API：提供现代查询接口。
• [ ] 🌐 多语言支持：实现国际化（I18n）。

🤝 贡献

我们欢迎贡献！以下是开始贡献的步骤：

1. 🍴 分叉 仓库。
2. 🌿 创建分支：用于开发新功能（git checkout -b amazing-feature）。
3. 💻 编写代码：实现改进。
4. ✅ 测试：使用npm test进行测试。
5. 📤 提交 拉取请求。

开发命令

npm run build    # 构建TypeScript项目
npm run dev      # 开发模式  
npm run test     # 运行测试套件
npm run format   # 使用Prettier进行代码格式化

📄 许可证

本项目采用 MIT许可证，详情请参阅 LICENSE 文件。

由 Ryan Cardin 用心打造。

🔗 链接与资源

• 📦 NPM包：@ryancardin/noaa-tides-currents-mcp-server
• 🏪 Smithery：自动安装到Claude桌面
• 🌊 NOAA CO - OPS：NOAA官方数据门户
• 🤖 MCP协议：模型上下文协议文档
• ⚡ FastMCP：FastMCP框架