MCP Open Meteo Server

A comprehensive Model Context Protocol (MCP) server for accessing Open Meteo weather data and services. This server provides multiple tools to interact with various Open Meteo APIs, including current weather, forecasts, historical data, air quality, marine weather, and climate data.

Features

🌤️ Weather Services

• Current Weather - Real-time weather conditions for any location
• Weather Forecast - Detailed hourly and daily forecasts up to 16 days
• Historical Weather - Past weather data with comprehensive statistics

🌍 Location Services

• Geocoding - Search for locations and get coordinates
• Reverse Geocoding - Get location details from coordinates

🌊 Environmental Data

• Air Quality - Air pollution data with AQI indices (European & US)
• Marine Weather - Wave heights, ocean currents, and marine conditions
• Climate Data - Long-term climate projections and historical climate data

📊 Data Features

• Multiple temperature units (Celsius/Fahrenheit)
• Comprehensive weather statistics
• Health recommendations for air quality
• Marine safety information
• Climate model comparisons

Installation

Local Development

# Clone the repository
git clone <repository-url>
cd mcp-open-meteo

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

Docker Usage

Build and Run

# Build the Docker image
npm run docker:build

# Run the container
npm run docker:run

Using Docker Compose

# Build and start with compose
npm run docker:up

# Stop the service
npm run docker:down

# View logs
npm run docker:logs

Usage

MCP Configuration

Local Node.js

Add this server to your MCP client configuration:

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

Docker

{
  "mcpServers": {
    "open-meteo": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "open-meteo-mcp-server"]
    }
  }
}

Docker Compose

{
  "mcpServers": {
    "open-meteo": {
      "command": "docker-compose",
      "args": ["run", "--rm", "open-meteo-mcp"]
    }
  }
}

Available Tools

1. Get Current Weather

Get real-time weather conditions for any location.

{
  "name": "get_current_weather",
  "arguments": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "units": "celsius"
  }
}

Parameters:

• latitude (required): Latitude coordinate (-90 to 90)
• longitude (required): Longitude coordinate (-180 to 180)
• units (optional): Temperature units ("celsius" or "fahrenheit", default: "celsius")

2. Get Weather Forecast

Get detailed weather forecasts with hourly and daily data.

{
  "name": "get_weather_forecast",
  "arguments": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "days": 7,
    "hourly": true,
    "daily": true,
    "units": "celsius"
  }
}

Parameters:

• latitude (required): Latitude coordinate (-90 to 90)
• longitude (required): Longitude coordinate (-180 to 180)
• days (optional): Number of forecast days (1-16, default: 7)
• hourly (optional): Include hourly forecast (default: true)
• daily (optional): Include daily forecast (default: true)
• units (optional): Temperature units (default: "celsius")

3. Get Historical Weather

Retrieve historical weather data for analysis.

{
  "name": "get_historical_weather",
  "arguments": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "start_date": "2023-01-01",
    "end_date": "2023-01-31",
    "daily": true,
    "hourly": false,
    "units": "celsius"
  }
}

Parameters:

• latitude (required): Latitude coordinate (-90 to 90)
• longitude (required): Longitude coordinate (-180 to 180)
• start_date (required): Start date in YYYY-MM-DD format
• end_date (required): End date in YYYY-MM-DD format
• daily (optional): Include daily data (default: true)
• hourly (optional): Include hourly data (default: false)
• units (optional): Temperature units (default: "celsius")

4. Search Locations

Find locations by name and get their coordinates.

{
  "name": "search_locations",
  "arguments": {
    "name": "New York",
    "count": 10,
    "language": "en"
  }
}

Parameters:

• name (required): Location name to search for
• count (optional): Maximum number of results (1-100, default: 10)
• language (optional): Language for results (default: "en")

5. Get Air Quality

Retrieve air quality data and forecasts.

{
  "name": "get_air_quality",
  "arguments": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "days": 3,
    "current": true
  }
}

Parameters:

• latitude (required): Latitude coordinate (-90 to 90)
• longitude (required): Longitude coordinate (-180 to 180)
• days (optional): Number of forecast days (1-5, default: 3)
• current (optional): Include current air quality (default: true)

6. Get Marine Weather

Get marine weather forecasts including waves and ocean conditions.

{
  "name": "get_marine_weather",
  "arguments": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "days": 7
  }
}

Parameters:

• latitude (required): Latitude coordinate (-90 to 90)
• longitude (required): Longitude coordinate (-180 to 180)
• days (optional): Number of forecast days (1-7, default: 7)

7. Get Climate Data

Access climate change scenarios and long-term climate data.

{
  "name": "get_climate_data",
  "arguments": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "start_date": "2020-01-01",
    "end_date": "2020-12-31",
    "models": ["EC_Earth3P_HR", "FGOALS_f3_H"]
  }
}

Parameters:

• latitude (required): Latitude coordinate (-90 to 90)
• longitude (required): Longitude coordinate (-180 to 180)
• start_date (required): Start date in YYYY-MM-DD format
• end_date (required): End date in YYYY-MM-DD format
• models (optional): Array of climate models to use

Available Climate Models

• EC_Earth3P_HR - EC-Earth3P-HR (High Resolution European Centre)
• FGOALS_f3_H - FGOALS-f3-H (Chinese Academy of Sciences)
• HiRAM_SIT_HR - HiRAM-SIT-HR (NOAA High Resolution)
• MRI_AGCM3_2_S - MRI-AGCM3-2-S (Japan Meteorological Research Institute)
• EC_Earth3P - EC-Earth3P (European Centre Standard)
• FGOALS_f3 - FGOALS-f3 (Chinese Academy of Sciences Standard)
• MPI_ESM1_2_HR - MPI-ESM1-2-HR (Max Planck Institute High Resolution)
• MRI_AGCM3_2 - MRI-AGCM3-2 (Japan Meteorological Research Institute Standard)

Example Workflows

1. Complete Weather Analysis for a City

# 1. First, search for the location
search_locations: {name: "London, UK"}

# 2. Get current weather
get_current_weather: {latitude: 51.5074, longitude: -0.1278}

# 3. Get 7-day forecast
get_weather_forecast: {latitude: 51.5074, longitude: -0.1278, days: 7}

# 4. Check air quality
get_air_quality: {latitude: 51.5074, longitude: -0.1278}

2. Historical Weather Analysis

# Compare weather patterns between years
get_historical_weather: {
  latitude: 40.7128, 
  longitude: -74.0060, 
  start_date: "2022-06-01", 
  end_date: "2022-08-31"
}

get_historical_weather: {
  latitude: 40.7128, 
  longitude: -74.0060, 
  start_date: "2023-06-01", 
  end_date: "2023-08-31"
}

3. Marine Weather for Sailing

# Check marine conditions before sailing
get_marine_weather: {latitude: 36.1699, longitude: -5.3543, days: 3}
get_weather_forecast: {latitude: 36.1699, longitude: -5.3543, days: 3}

4. Climate Research

# Long-term climate analysis
get_climate_data: {
  latitude: 59.3293,
  longitude: 18.0686,
  start_date: "1990-01-01",
  end_date: "2020-12-31",
  models: ["EC_Earth3P_HR", "MPI_ESM1_2_HR"]
}

Data Sources

This server uses the following Open Meteo APIs:

• Weather API - Current weather and forecasts
• Historical Weather API - Past weather data
• Geocoding API - Location search and coordinates
• Air Quality API - Pollution and air quality data
• Marine Weather API - Ocean and wave conditions
• Climate API - Long-term climate data and projections

Development

Project Structure

src/
├── index.ts              # Main MCP server
├── types/
│   └── openmeteo.ts     # TypeScript types and schemas
└── tools/
    ├── current-weather.ts    # Current weather tool
    ├── weather-forecast.ts   # Weather forecast tool
    ├── historical-weather.ts # Historical weather tool
    ├── geocoding.ts         # Location search tool
    ├── air-quality.ts       # Air quality tool
    ├── marine-weather.ts    # Marine weather tool
    └── climate-data.ts      # Climate data tool

Build Commands

# Install dependencies
npm install

# Build TypeScript
npm run build

# Start development server
npm run dev

# Watch for changes
npm run watch

# Clean build directory
npm run clean

Adding New Tools

1. Create a new tool file in src/tools/
2. Export an async function that handles the tool logic
3. Add the tool to the imports in src/index.ts
4. Add the tool definition to the ListToolsRequestSchema handler
5. Add the tool case to the CallToolRequestSchema handler

API Rate Limits

Open Meteo APIs have the following rate limits:

• Free tier: 10,000 API calls per day
• Commercial tier: Higher limits available

For high-volume usage, consider:

• Implementing caching mechanisms
• Using the commercial API for higher rate limits
• Batching requests when possible

Error Handling

The server includes comprehensive error handling:

• Input validation for all parameters
• API error response handling
• Network timeout and retry logic
• Informative error messages

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details

Acknowledgments

• Open Meteo for providing free weather APIs
• Model Context Protocol for the MCP specification

Support

For issues and questions:

1. Check the Open Meteo documentation
2. Review the error messages for specific guidance
3. Open an issue in this repository for bugs or feature requests