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 formatend_date(required): End date in YYYY-MM-DD formatdaily(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 forcount(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 formatend_date(required): End date in YYYY-MM-DD formatmodels(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
- Create a new tool file in
src/tools/ - Export an async function that handles the tool logic
- Add the tool to the imports in
src/index.ts - Add the tool definition to the
ListToolsRequestSchemahandler - Add the tool case to the
CallToolRequestSchemahandler
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
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- 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:
- Check the Open Meteo documentation
- Review the error messages for specific guidance
- Open an issue in this repository for bugs or feature requests