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框架