dhhuston/open-meteo-mcp

🌤️ Open Meteo MCP Server v2.0

A comprehensive Model Context Protocol (MCP) server that provides complete access to Open Meteo's weather APIs with 17 specialized tools for Claude Desktop integration.

🚀 Quick Start

One-Command Installation

chmod +x install.sh && ./install.sh

This automatically:

• ✅ Checks Node.js requirements (18+)
• 📦 Installs dependencies
• 🔨 Builds the project
• 🧪 Tests functionality
• 🔧 Configures Claude Desktop
• 📋 Creates config backups

Manual Installation

# Install dependencies
npm install

# Build the project
npm run build

# Test the server
npm run test

System Requirements

• Node.js: 18.0.0 or higher
• npm: Latest version recommended
• Claude Desktop: For MCP integration

🔧 Configuration

Automatic Configuration

The install script automatically configures Claude Desktop. After installation:

1. Restart Claude Desktop if it's running
2. The server appears as "open-meteo" in Claude
3. Ask Claude: "What's the weather in London?"

Manual Configuration

Add to ~/.config/claude-desktop/config.json:

{
  "mcpServers": {
    "open-meteo": {
      "command": "node",
      "args": ["/absolute/path/to/build/index.js"],
      "env": {}
    }
  }
}

Remove Configuration

npm run claude:remove

🛠️ Available Tools (17 Total)

🗺️ Geocoding & Location Tools (2 tools)

• search_locations - Find places by name with detailed geographic information
• get_location_details - Get comprehensive location data including coordinates, timezone, elevation

🌡️ Current & Forecast Weather (7 tools)

• get_current_weather (legacy) - Basic current conditions
• get_hourly_forecast (legacy) - Basic hourly forecasts
• get_daily_forecast (legacy) - Basic daily forecasts
• get_current_weather_enhanced - Complete current weather with all variables
• get_hourly_forecast_enhanced - Detailed hourly forecasts with 50+ variables
• get_daily_forecast_enhanced - Comprehensive daily forecasts with all metrics
• get_custom_weather_data - Fully customizable weather data requests

📊 Historical & Climate Analysis (3 tools)

• get_historical_weather - Access 80+ years of historical weather data
• get_historical_comparison - Compare weather across multiple years
• get_climate_statistics - Long-term climate statistics and trends

🌊 Specialized Weather Data (4 tools)

• get_marine_forecast - Wave height, ocean currents, swell conditions
• get_air_quality - PM2.5, ozone, pollen with health categories
• get_elevation_data - Elevation data for any location
• get_uv_index - UV forecasts with health protection recommendations

💡 Natural Language Usage Examples

• "What's the weather in London?" → Uses geocoding + current weather
• "Compare this week's rainfall to last year" → Historical comparison
• "Is it safe to surf in Santa Monica tomorrow?" → Marine + UV forecasts
• "Show me soil moisture data for farming areas" → Custom weather variables

🧪 Testing & Development

Test Commands

# Test with MCP Inspector (opens browser)
npm run test

# Test tool listing
npm run test:tools

# Test current weather (NYC example)  
npm run test:weather

# Development mode with file watching
npm run watch

Manual Testing

# List available tools
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | node build/index.js

# Test current weather
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "get_current_weather", "arguments": {"latitude": 40.7128, "longitude": -74.0060}}}' | node build/index.js

📋 Example Response

Current weather for New York City:

{
  "location": {
    "latitude": 40.7128,
    "longitude": -74.006
  },
  "current_weather": {
    "temperature": 23.5,
    "windspeed": 9.7,
    "winddirection": 132,
    "weathercode": 1,
    "time": "2025-07-14T01:45"
  }
}

🏗️ Architecture v2.0

• Modular design: Organized tool classes for different weather domains
• 17 specialized tools: Complete Open Meteo API coverage
• Type-safe: Full TypeScript with comprehensive Zod validation
• Backward compatible: Legacy tools preserved for existing integrations
• Comprehensive validation: User-friendly error messages and input validation
• Flexible variables: Support for 100+ weather variables across all timeframes

🤝 Integration Tips

Using with Claude Desktop

1. Natural language: "What's the weather like in Tokyo right now?"
2. Location search: "Find weather for Paris, France vs Paris, Texas"
3. Historical analysis: "How does this year's rainfall compare to the last decade?"
4. Specialized data: "What are the surfing conditions in Malibu?"
5. Custom requests: "Show me soil moisture and UV data for farming"

Advanced Use Cases

• Climate research: Multi-decade temperature and precipitation analysis
• Marine activities: Wave forecasts, ocean conditions, tidal planning
• Health monitoring: Air quality alerts, UV protection recommendations
• Agriculture: Soil conditions, evapotranspiration, growing degree days
• Energy analysis: Solar radiation data, wind patterns at multiple altitudes
• Travel planning: Historical weather patterns, seasonal comparisons

📁 Project Structure

open-meteo-mcp-server/
├── src/
│   ├── index.ts          # Main server with tool routing
│   ├── schemas/          # Zod validation schemas
│   │   ├── common.ts     # Shared validation utilities
│   │   ├── geocoding.ts  # Location search schemas
│   │   └── weather.ts    # Weather data schemas
│   ├── tools/            # Modular tool implementations
│   │   ├── geocoding.ts  # Location search & details
│   │   ├── forecast.ts   # Weather forecasts & current conditions
│   │   ├── historical.ts # Historical weather & climate analysis
│   │   └── specialized.ts# Marine, air quality, UV, elevation
│   ├── utils/            # Utility functions
│   │   ├── api-client.ts # Open Meteo API wrapper
│   │   ├── variables.ts  # Weather variable definitions
│   │   └── validation.ts # Input validation helpers
│   └── types/            # TypeScript type definitions
│       └── open-meteo.ts # API response types
├── build/               # Compiled JavaScript output
├── install.sh           # Automated installation script
├── package.json         # Dependencies and scripts  
├── tsconfig.json        # TypeScript configuration
├── mcp-config.json      # MCP server configuration
└── README.md           # This documentation

📈 What's New in v2.0

🚀 Major Enhancements

• 17 tools (up from 3) covering all Open Meteo APIs
• 100+ weather variables across all timeframes
• Location search with natural language support
• 80+ years of historical weather data access
• Specialized APIs for marine, air quality, UV, elevation

🛠️ Technical Improvements

• Modular architecture with organized tool classes
• Comprehensive validation with user-friendly error messages
• Full TypeScript coverage with generated types
• Backward compatibility - all legacy tools still work
• Enhanced documentation with usage examples

🌍 New Data Sources

• Geocoding: Global location search and coordinate lookup
• Historical: Weather data from 1940+ with climate statistics
• Marine: Wave forecasts, ocean currents, swell analysis
• Air Quality: PM2.5, ozone, pollen with health categories
• Solar: UV index with protection recommendations

📄 License

MIT License - feel free to use and modify for your projects.