# 🌊 NOAA Tides & Currents MCP Server
<div align="center">
[](https://www.npmjs.com/package/@ryancardin/noaa-tides-currents-mcp-server)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[](https://smithery.ai/server/@RyanCardin15/noaa-tidesandcurrents-mcp)
**🚀 Lightning-fast access to NOAA's oceanic and atmospheric data through MCP**
*Your one-stop solution for tides, currents, weather, astronomy, and climate data*
[📦 Quick Start](#-quick-start) • [🛠️ Tools](#️-available-tools) • [📖 Examples](#-usage-examples) • [🏗️ Advanced](#️-advanced-usage)
</div>
---
## ✨ What Makes This Awesome
🌊 **25+ Specialized Tools** - From basic tide data to advanced climate projections
⚡ **Lightning Fast** - Built on FastMCP for optimal performance
🎯 **Zero Config** - Works out of the box with Claude Desktop
🌍 **Comprehensive Data** - Water levels, currents, weather, moon phases, sun data
📊 **Climate Research Ready** - Sea level trends, flooding projections, extreme events
🚀 **NPX Ready** - Install and run with a single command
---
## 🚀 Quick Start
### ⚡ NPX Installation (Recommended)
```bash
# Install and run immediately - no setup required!
npx @ryancardin/noaa-tides-currents-mcp-server
# Or use the shorter alias
npx noaa-mcp
```
#### 🔌 Transport Modes
**STDIO Mode (Default - MCP Protocol)**
```bash
# Standard MCP server for Claude Desktop integration
npx @ryancardin/noaa-tides-currents-mcp-server
# Or use the shorter alias
npx noaa-mcp
```
**HTTP Streamable Mode (Web Integration)**
```bash
# Start HTTP server on default port 3000
npx @ryancardin/noaa-tides-currents-mcp-server --http
# Specify custom port
npx @ryancardin/noaa-tides-currents-mcp-server --http --port 8080
# Using shorter alias
npx noaa-mcp --http --port 8080
# Access via Server-Sent Events
curl http://localhost:3000/sse
```
### 🎯 Claude Desktop Integration
Install directly to Claude Desktop via [Smithery](https://smithery.ai/server/@RyanCardin15/tidesandcurrents):
```bash
npx -y @smithery/cli install @RyanCardin15/tidesandcurrents --client claude
```
### 🔧 Manual Development Setup
```bash
# Clone and build
git clone https://github.com/RyanCardin15/NOAA-Tides-And-Currents-MCP.git
cd NOAA-Tides-And-Currents-MCP
npm install && npm run build
# Start the server
npm start
# Test with FastMCP
npx fastmcp dev dist/index.js
```
---
## 🛠️ Available Tools
<details>
<summary><strong>🌊 Water Data Tools (6 tools)</strong></summary>
### Water Levels & Tides
- **`get_water_levels`** - Real-time and historical water level data
- **`get_tide_predictions`** - High/low tide predictions and continuous data
- **`get_currents`** - Real-time and historical current measurements
- **`get_current_predictions`** - Current speed and direction forecasts
- **`get_meteorological_data`** - Wind, air temp, water temp, pressure, etc.
### Station Information
- **`get_stations`** - Search and list monitoring stations
- **`get_station_details`** - Detailed station metadata and capabilities
</details>
<details>
<summary><strong>🔬 Climate & Research Tools (9 tools)</strong></summary>
### Sea Level Analysis
- **`get_sea_level_trends`** - Long-term sea level rise trends and rates
- **`get_extreme_water_levels`** - Statistical analysis of extreme events
### High Tide Flooding Analysis
- **`get_high_tide_flooding_daily`** - Daily flood event counts
- **`get_high_tide_flooding_monthly`** - Monthly flooding patterns
- **`get_high_tide_flooding_seasonal`** - Seasonal flood analysis
- **`get_high_tide_flooding_annual`** - Yearly flooding trends
- **`get_high_tide_flooding_projections`** - Future flood risk scenarios
- **`get_high_tide_flooding_likelihoods`** - Daily flood probability
### Historical Extremes
- **`get_top_ten_water_levels`** - Highest/lowest water levels on record
</details>
<details>
<summary><strong>🌙 Astronomy Tools (7 tools)</strong></summary>
### Moon Phase Calculations
- **`get_moon_phase`** - Current moon phase and illumination
- **`get_moon_phases_range`** - Moon phases over date ranges
- **`get_next_moon_phase`** - Find next new/full/quarter moons
### Solar Calculations
- **`get_sun_times`** - Sunrise, sunset, dawn, dusk times
- **`get_sun_times_range`** - Solar times over date ranges
- **`get_sun_position`** - Real-time sun azimuth and elevation
- **`get_next_sun_event`** - Next sunrise, sunset, or solar noon
</details>
<details>
<summary><strong>⚙️ Configuration Tools (1 tool)</strong></summary>
### API Parameters
- **`get_parameter_definitions`** - Valid values for all API parameters
</details>
---
## 📖 Usage Examples
### 🌊 Get Current Tide Conditions
```bash
# Get latest water levels for Boston Harbor
get_water_levels station="8443970" date="latest"
# Get today's tide predictions for Miami
get_tide_predictions station="8723214" begin_date="today" end_date="today" interval="hilo"
```
### 🌀 Hurricane Preparedness
```bash
# Get extreme water level statistics for storm planning
get_extreme_water_levels station="8518750" units="english"
# Check flooding likelihood for tomorrow
get_high_tide_flooding_likelihoods station="8518750" date="2024-12-16" threshold="minor"
```
### 🔬 Climate Research
```bash
# Analyze 30-year sea level trends
get_sea_level_trends station="8518750" affiliation="US"
# Get high tide flooding projections for 2050s under intermediate sea level rise
get_high_tide_flooding_projections station="8518750" scenario="intermediate" decade="2050s"
```
### 🌙 Astronomy & Navigation
```bash
# Get tonight's moon phase for navigation
get_moon_phase date="2024-12-15" latitude="42.3601" longitude="-71.0589"
# Calculate sunrise/sunset for sailing
get_sun_times date="2024-12-15" latitude="25.7617" longitude="-80.1918" timezone="America/New_York"
```
### 🎣 Fishing & Recreation
```bash
# Best fishing times with current predictions
get_current_predictions station="ACT0446" date="today" interval="MAX_SLACK"
# Wind and weather conditions
get_meteorological_data station="8443970" product="wind" date="today"
```
---
## 🏗️ Advanced Usage
### 🔧 Development & Testing
```bash
# Run in development mode (stdio)
npm run dev
# Development with HTTP transport
npm run dev:http
# Production builds with different transports
npm start # STDIO mode (default)
npm run start:http # HTTP on port 3000
npm run start:http:3001 # HTTP on port 3001
npm run start:http:8080 # HTTP on port 8080
# Inspect server capabilities
npx fastmcp inspect dist/index.js
```
### 🌐 HTTP Stream Integration
When running in HTTP mode, the server provides Server-Sent Events (SSE) at `/sse`:
```bash
# Start HTTP server
npx @ryancardin/noaa-tides-currents-mcp-server --http --port 3000
# Test the endpoint
curl -N http://localhost:3000/sse
# Or integrate with web applications
fetch('http://localhost:3000/sse')
.then(response => response.body.getReader())
.then(reader => {
// Handle streaming MCP responses
});
```
**Use Cases for HTTP Mode:**
- 🌐 **Web Applications** - Integrate with React, Vue, Angular apps
- 📱 **Mobile Apps** - REST-like access from mobile applications
- 🔗 **API Gateways** - Proxy through load balancers or API gateways
- 🧪 **Testing** - Easy curl-based testing and debugging
### 📊 Data Formats & Export
All tools support multiple output formats:
- **JSON** (default) - Perfect for programmatic use
- **XML** - Legacy system integration
- **CSV** - Direct spreadsheet import
### 🌍 Global Station Coverage
- **13,000+ stations** worldwide
- **Real-time data** from NOAA's CO-OPS network
- **Historical records** dating back decades
- **Global tide predictions** and current forecasts
---
## 🚦 API Endpoints
This server integrates with three NOAA APIs:
| API | Purpose | Base URL |
|-----|---------|----------|
| **Data API** | Real-time observations & predictions | `api.tidesandcurrents.noaa.gov/api/prod/` |
| **Metadata API** | Station information & capabilities | `api.tidesandcurrents.noaa.gov/mdapi/prod/` |
| **Derived Products API** | Climate analysis & research data | `api.tidesandcurrents.noaa.gov/dpapi/prod/` |
---
## 🛠️ Technical Details
### Architecture
- **🚀 FastMCP Framework** - High-performance MCP server
- **📝 TypeScript** - Full type safety and IntelliSense
- **🔧 Zod Validation** - Runtime parameter validation
- **⚡ Axios HTTP Client** - Reliable API communication
- **🌙 SunCalc Integration** - Precise astronomical calculations
### Transport Options
- **📡 STDIO Transport** - Standard MCP protocol for desktop clients
- **🌐 HTTP Stream Transport** - Server-Sent Events for web integration
- **🔄 Dual Mode Support** - Switch between transports via command-line flags
### System Requirements
- **Node.js** 18+
- **NPM** 8+
- **MCP Client** (Claude Desktop, etc.)
### Package Size
- **📦 Bundled**: 43.9 KB
- **📂 Installed**: 286.2 KB
- **⚡ Load Time**: <100ms
---
## 🐛 Troubleshooting
<details>
<summary><strong>Common Issues & Solutions</strong></summary>
### Server Won't Start
```bash
# Check Node.js version
node --version # Should be 18+
# Rebuild TypeScript
npm run build
```
### API Errors
- **Invalid Station ID**: Use `get_stations` to find valid stations
- **Date Format Issues**: Use YYYYMMDD or MM/DD/YYYY formats
- **Rate Limiting**: NOAA APIs have usage limits - space out requests
### MCP Connection Issues
- Ensure Claude Desktop MCP settings are configured correctly
- Check that the server binary has execute permissions: `chmod +x dist/index.js`
</details>
---
## 📈 Roadmap
- [ ] 🌊 **Real-time Alerts** - Webhook support for tide/weather alerts
- [ ] 📱 **Mobile SDK** - React Native integration
- [ ] 🗺️ **GIS Integration** - Shapefile and KML export
- [ ] 🤖 **AI Insights** - Automated pattern recognition
- [ ] ⚡ **GraphQL API** - Modern query interface
- [ ] 🌐 **Multi-language** - I18n support
---
## 🤝 Contributing
We love contributions! Here's how to get started:
1. **🍴 Fork** the repository
2. **🌿 Branch** for your feature (`git checkout -b amazing-feature`)
3. **💻 Code** your improvements
4. **✅ Test** with `npm test`
5. **📤 Submit** a pull request
### Development Commands
```bash
npm run build # Build TypeScript
npm run dev # Development mode
npm run test # Run test suite
npm run format # Format with Prettier
```
---
## 📄 License
**MIT License** - see [LICENSE](LICENSE) file for details.
Built with ❤️ by [Ryan Cardin](https://github.com/RyanCardin15)
---
## 🔗 Links & Resources
- **📦 NPM Package**: [@ryancardin/noaa-tides-currents-mcp-server](https://www.npmjs.com/package/@ryancardin/noaa-tides-currents-mcp-server)
- **🏪 Smithery**: [Auto-install for Claude Desktop](https://smithery.ai/server/@RyanCardin15/noaa-tidesandcurrents-mcp)
- **🌊 NOAA CO-OPS**: [Official NOAA Data Portal](https://tidesandcurrents.noaa.gov/)
- **🤖 MCP Protocol**: [Model Context Protocol Docs](https://modelcontextprotocol.io/)
- **⚡ FastMCP**: [FastMCP Framework](https://github.com/jlowin/fastmcp)
<div align="center">
**⭐ Star this repo if it helped you!**
Made possible by NOAA's commitment to open oceanic data 🌊
</div>