国家海洋和大气管理局潮汐和水流-MCP
项目介绍
技术文档摘要
🌊 NOAA 潮汐与水流 MCP 服务器
<div align="center">
🚀 快速访问 NOAA 的海洋和大气数据通过 MCP
一站式解决方案，提供潮汐、水流、天气、天文和气候数据
</div>✨ 为什么这很酷
🌊 25+ 专业工具 - 从基本潮汐数据到高级气候预测
⚡ 闪电般快速 - 基于 FastMCP 构建以实现最佳性能
🎯 零配置 - 直接在 Claude Desktop 上运行
🌍 全面的数据 - 水位、水流、天气、月相、太阳数据
📊 气候研究准备就绪 - 海平面上升趋势、洪水预测、极端事件
🚀 NPX 准备就绪 - 单个命令安装和运行
🚀 快速开始
⚡ NPX 安装（推荐）
# 安装并立即运行 - 不需要设置！
npx @ryancardin/noaa-tides-currents-mcp-server
# 或使用较短的别名
npx noaa-mcp
🔌 运输模式
STDIO 模式（默认 - MCP 协议）
# 标准 MCP 服务器用于 Claude Desktop 集成
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
# 通过 Server-Sent Events 访问
curl http://localhost:3000/sse
🎯 Claude Desktop 集成
通过 Smithery 直接安装到 Claude Desktop：
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
🛠️ 可用工具
<details> <summary><strong>🌊 水数据工具（6 个工具）</strong></summary>水位与潮汐
get_water_levels- 实时和历史水位数据get_tide_predictions- 高低潮预测和连续数据get_currents- 实时和历史水流测量get_current_predictions- 水流速度和方向预测get_meteorological_data- 风、气温、水温、气压等
站点信息
get_stations- 搜索和列出监测站get_station_details- 详细站点元数据和功能
海平面上升分析
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- 最高/最低水位记录
月亮相位计算
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- 下一个日出、日落或太阳正午
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 提供 Server-Sent Events (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 - 直接导入电子表格
🌍 全球站点覆盖
- 全球 13,000+ 站点
- 实时数据 来自 NOAA 的 CO-OPS 网络
- 历史记录 可追溯几十年
- 全球潮汐预测 和水流预报
🚦 API 端点
此服务器集成了三个 NOAA API：
| API | 目的 | 基础 URL |
|---|---|---|
| 数据 API | 实时观测及预测 | api.tidesandcurrents.noaa.gov/api/prod/ |
| 元数据 API | 站点信息及功能 | api.tidesandcurrents.noaa.gov/mdapi/prod/ |
| 衍生产品 API | 气候分析及研究数据 | api.tidesandcurrents.noaa.gov/dpapi/prod/ |
🛠️ 技术细节
架构
- 🚀 FastMCP 框架 - 高性能 MCP 服务器
- 📝 TypeScript - 完整类型安全和 IntelliSense
- 🔧 Zod 验证 - 运行时参数验证
- ⚡ Axios HTTP 客户端 - 可靠的 API 通信
- 🌙 SunCalc 集成 - 精确的天文学计算
传输选项
- 📡 STDIO 传输 - 用于桌面客户端的标准 MCP 协议
- 🌐 HTTP 流传输 - 用于 Web 集成的 Server-Sent Events
- 🔄 双模式支持 - 通过命令行标志切换传输方式
系统要求
- Node.js 18+
- NPM 8+
- MCP 客户端（Claude Desktop 等）
包大小
- 📦 打包: 43.9 KB
- 📂 安装: 286.2 KB
- ⚡ 加载时间: <100ms
🐛 故障排除
<details> <summary><strong>常见问题及解决方法</strong></summary>服务器无法启动
# 检查 Node.js 版本
node --version # 应该是 18+
# 重新构建 TypeScript
npm run build
API 错误
- 无效站点 ID: 使用
get_stations查找有效站点 - 日期格式问题: 使用 YYYYMMDD 或 MM/DD/YYYY 格式
- 速率限制: NOAA API 有使用限制 - 请间隔请求
MCP 连接问题
- 确保 Claude Desktop MCP 设置正确配置
- 检查服务器二进制文件是否有执行权限：
chmod +x dist/index.js
📈 发展路线图
- 🌊 实时警报 - 支持潮汐/天气警报的 webhook
- 📱 移动 SDK - React Native 集成
- 🗺️ GIS 集成 - Shapefile 和 KML 导出
- 🤖 AI 洞察 - 自动化模式识别
- ⚡ GraphQL API - 现代查询接口
- 🌐 多语言 - 国际化支持
🤝 贡献
我们热爱贡献！这是如何开始的：
- 🍴 分支 仓库
- 🌿 分支 用于你的特性 (
git checkout -b amazing-feature) - 💻 编码 你的改进
- ✅ 测试 使用
npm test - 📤 提交 一个拉取请求
开发命令
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 Desktop
- 🌊 NOAA CO-OPS: 官方 NOAA 数据门户
- 🤖 MCP 协议: 模型上下文协议文档
- ⚡ FastMCP: FastMCP 框架
⭐ 如果这个仓库对你有帮助，请给它点赞！
得益于 NOAA 对开放海洋数据的承诺 🌊
</div>