open-meteo-mcp-server

v1.3.1

Published

3 days ago

Model Context Protocol server for Open-Meteo weather APIs

0High
0Medium
0Low

cm3r

mcp weather open-meteo forecast api

Open-Meteo MCP Server

A comprehensive Model Context Protocol (MCP) server that provides access to Open-Meteo weather APIs for use with Large Language Models.

Features

This MCP server provides complete access to Open-Meteo APIs, including:

Core Weather APIs

Weather Forecast (weather_forecast) - 7-day forecasts with hourly and daily resolution
Weather Archive (weather_archive) - Historical ERA5 data from 1940 to present
Air Quality (air_quality) - PM2.5, PM10, ozone, nitrogen dioxide, pollen, European/US AQI indices, UV index and other pollutants
Marine Weather (marine_weather) - Wave height, wave period, wave direction and sea surface temperature
Elevation (elevation) - Digital elevation model data for given coordinates
Geocoding (geocoding) - Search locations worldwide by name or postal code, get coordinates and detailed location information

Specialized Weather Models

DWD ICON (dwd_icon_forecast) - German weather service high-resolution model for Europe
NOAA GFS (gfs_forecast) - US weather service global model with high-resolution North America data
Météo-France (meteofrance_forecast) - French weather service AROME and ARPEGE models
ECMWF (ecmwf_forecast) - European Centre for Medium-Range Weather Forecasts
JMA (jma_forecast) - Japan Meteorological Agency high-resolution model for Asia
MET Norway (metno_forecast) - Norwegian weather service for Nordic countries
Environment Canada GEM (gem_forecast) - Canadian weather service model

Advanced Forecasting Tools

Flood Forecast (flood_forecast) - River discharge and flood forecasts from GloFAS (Global Flood Awareness System)
Seasonal Forecast (seasonal_forecast) - Long-range forecasts up to 9 months ahead
Climate Projections (climate_projection) - CMIP6 climate change projections for different warming scenarios
Ensemble Forecast (ensemble_forecast) - Multiple model runs showing forecast uncertainty

Installation

Requirements

Node.js >= 22.0.0

Method 1: Using npx (Recommended)

No installation required! The server will run directly via npx.

Method 2: Global Installation via npm

npm install -g open-meteo-mcp-server

Method 3: From Source (Development)

# Clone the repository
git clone https://github.com/cmer81/open-meteo-mcp.git
cd open-meteo-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Claude Desktop Configuration

Simple Configuration (Recommended)

Add the following configuration to your Claude Desktop config file:

{
  "mcpServers": {
    "open-meteo": {
      "command": "npx",
      "args": ["-y", "-p", "open-meteo-mcp-server", "open-meteo-mcp-server"]
    }
  }
}

Full Configuration (with environment variables)

{
  "mcpServers": {
    "open-meteo": {
      "command": "npx",
      "args": ["-y", "-p", "open-meteo-mcp-server", "open-meteo-mcp-server"],
      "env": {
        "OPEN_METEO_API_URL": "https://api.open-meteo.com",
        "OPEN_METEO_AIR_QUALITY_API_URL": "https://air-quality-api.open-meteo.com",
        "OPEN_METEO_MARINE_API_URL": "https://marine-api.open-meteo.com",
        "OPEN_METEO_ARCHIVE_API_URL": "https://archive-api.open-meteo.com",
        "OPEN_METEO_SEASONAL_API_URL": "https://seasonal-api.open-meteo.com",
        "OPEN_METEO_ENSEMBLE_API_URL": "https://ensemble-api.open-meteo.com",
        "OPEN_METEO_GEOCODING_API_URL": "https://geocoding-api.open-meteo.com",
        "OPEN_METEO_FLOOD_API_URL": "https://flood-api.open-meteo.com",
        "OPEN_METEO_CLIMATE_API_URL": "https://climate-api.open-meteo.com"
      }
    }
  }
}

Local Development Configuration

If you're developing locally or installed from source:

{
  "mcpServers": {
    "open-meteo": {
      "command": "node",
      "args": ["/path/to/open-meteo-mcp/dist/index.js"],
      "env": {
        "OPEN_METEO_API_URL": "https://api.open-meteo.com",
        "OPEN_METEO_AIR_QUALITY_API_URL": "https://air-quality-api.open-meteo.com",
        "OPEN_METEO_MARINE_API_URL": "https://marine-api.open-meteo.com",
        "OPEN_METEO_ARCHIVE_API_URL": "https://archive-api.open-meteo.com",
        "OPEN_METEO_SEASONAL_API_URL": "https://seasonal-api.open-meteo.com",
        "OPEN_METEO_ENSEMBLE_API_URL": "https://ensemble-api.open-meteo.com",
        "OPEN_METEO_GEOCODING_API_URL": "https://geocoding-api.open-meteo.com",
        "OPEN_METEO_FLOOD_API_URL": "https://flood-api.open-meteo.com",
        "OPEN_METEO_CLIMATE_API_URL": "https://climate-api.open-meteo.com"
      }
    }
  }
}

Custom Instance Configuration

If you're using your own Open-Meteo instance:

{
  "mcpServers": {
    "open-meteo": {
      "command": "npx",
      "args": ["-y", "-p", "open-meteo-mcp-server", "open-meteo-mcp-server"],
      "env": {
        "OPEN_METEO_API_URL": "https://your-meteo-api.example.com",
        "OPEN_METEO_AIR_QUALITY_API_URL": "https://air-quality-api.example.com",
        "OPEN_METEO_MARINE_API_URL": "https://marine-api.example.com",
        "OPEN_METEO_ARCHIVE_API_URL": "https://archive-api.example.com",
        "OPEN_METEO_SEASONAL_API_URL": "https://seasonal-api.example.com",
        "OPEN_METEO_ENSEMBLE_API_URL": "https://ensemble-api.example.com",
        "OPEN_METEO_GEOCODING_API_URL": "https://geocoding-api.example.com",
        "OPEN_METEO_FLOOD_API_URL": "https://flood-api.example.com"
      }
    }
  }
}

Streamable HTTP Transport

The server also supports Streamable HTTP transport for remote deployments. Set the TRANSPORT environment variable to http:

TRANSPORT=http PORT=3000 npx open-meteo-mcp-server

This starts an Express server on the specified port (default: 3000) with the MCP endpoint at /mcp. The HTTP transport supports session management with unique session IDs per client.

Using npm scripts

# Start in HTTP mode (production)
npm run start:http

# Development with auto-reload in HTTP mode
npm run dev:http

Docker Deployment

The server can be easily deployed using Docker.

Using Pre-built Image from GitHub Container Registry (Recommended)

Pull and run the official image:

# Pull the latest image
docker pull ghcr.io/cmer81/open-meteo-mcp:latest

# Run the container
docker run -d \
  --name open-meteo-mcp \
  -p 3000:3000 \
  ghcr.io/cmer81/open-meteo-mcp:latest

# Check health
curl http://localhost:3000/health

Available tags:

latest - Latest stable release
v1.x.x - Specific version (e.g., v1.1.3)
1 - Latest v1.x.x release
1.1 - Latest v1.1.x release

Using Docker Compose

The repository includes two Docker Compose configurations:

Production (uses pre-built image):

# Start with pre-built image from GitHub Container Registry
docker compose up -d

# View logs
docker compose logs -f

# Stop the server
docker compose down

Development (builds from source):

# Build and start from local source
docker compose -f docker-compose.dev.yml up -d

# Rebuild after code changes
docker compose -f docker-compose.dev.yml up -d --build

Building from Source

If you prefer to build the image yourself:

# Build the image
npm run docker:build
# or
docker build -t open-meteo-mcp-server .

# Run the container
npm run docker:run
# or
docker run -p 3000:3000 open-meteo-mcp-server

Environment Configuration

Copy .env.example to .env and customize as needed:

cp .env.example .env
# Edit .env with your configuration

Then update docker-compose.yml to use the .env file or pass environment variables directly.

Health Check

The HTTP server includes a health check endpoint:

curl http://localhost:3000/health
# Response: {"status":"ok"}

This endpoint is used by Docker's HEALTHCHECK and can be integrated with container orchestration platforms (Kubernetes, Docker Swarm, etc.).

Environment Variables

All environment variables are optional and have sensible defaults:

OPEN_METEO_API_URL - Base URL for Open-Meteo forecast API (default: https://api.open-meteo.com)
OPEN_METEO_AIR_QUALITY_API_URL - Air quality API URL (default: https://air-quality-api.open-meteo.com)
OPEN_METEO_MARINE_API_URL - Marine weather API URL (default: https://marine-api.open-meteo.com)
OPEN_METEO_ARCHIVE_API_URL - Historical data API URL (default: https://archive-api.open-meteo.com)
OPEN_METEO_SEASONAL_API_URL - Seasonal forecast API URL (default: https://seasonal-api.open-meteo.com)
OPEN_METEO_ENSEMBLE_API_URL - Ensemble forecast API URL (default: https://ensemble-api.open-meteo.com)
OPEN_METEO_GEOCODING_API_URL - Geocoding API URL (default: https://geocoding-api.open-meteo.com)
OPEN_METEO_FLOOD_API_URL - Flood forecast API URL (default: https://flood-api.open-meteo.com)
OPEN_METEO_CLIMATE_API_URL - Climate projection API URL (default: https://climate-api.open-meteo.com)
TRANSPORT - Transport mode: http for Streamable HTTP, omit for stdio (default: stdio)
PORT - HTTP server port when using HTTP transport (default: 3000)

Usage Examples

Geocoding and Location Search

Find the coordinates for Paris, France

Search for locations named "Berlin" and return the top 5 results

What are the coordinates for postal code 75001?

Search for "Lyon" in France only (countryCode: FR) with results in French (language: fr)

Find all cities named "London" in the United Kingdom with English descriptions

Basic Weather Forecast

Can you get me the weather forecast for Paris (48.8566, 2.3522) with temperature, humidity, and precipitation for the next 3 days?

Historical Weather Data

What were the temperatures in London during January 2023?

Air Quality Monitoring

What's the current air quality in Beijing with PM2.5 and ozone levels?

Marine Weather

Get me the wave height and sea surface temperature for coordinates 45.0, -125.0 for the next 5 days.

Flood Monitoring

Check the river discharge forecast for coordinates 52.5, 13.4 for the next 30 days.

Climate Projections

Show me temperature projections for New York from 2050 to 2070 using CMIP6 models.

API Parameters

Required Parameters

latitude : Latitude in WGS84 coordinate system (-90 to 90)
longitude : Longitude in WGS84 coordinate system (-180 to 180)

Hourly Weather Variables

temperature_2m : Temperature at 2 meters
relative_humidity_2m : Relative humidity
precipitation : Precipitation
wind_speed_10m : Wind speed at 10 meters
wind_direction_10m : Wind direction
pressure_msl : Mean sea level pressure
cloud_cover : Cloud cover percentage
weather_code : Weather condition code
visibility : Visibility
uv_index : UV index
And many more...

Daily Weather Variables

temperature_2m_max/min : Maximum/minimum temperatures
precipitation_sum : Total precipitation
wind_speed_10m_max : Maximum wind speed
sunrise/sunset : Sunrise and sunset times
weather_code : Weather condition code
uv_index_max : Maximum UV index

Air Quality Variables

pm10 : PM10 particles
pm2_5 : PM2.5 particles
carbon_monoxide : Carbon monoxide
nitrogen_dioxide : Nitrogen dioxide
ozone : Ozone
sulphur_dioxide : Sulfur dioxide
ammonia : Ammonia
dust : Dust particles
alder_pollen : Alder pollen (Europe only)
birch_pollen : Birch pollen (Europe only)
grass_pollen : Grass pollen (Europe only)
mugwort_pollen : Mugwort pollen (Europe only)
olive_pollen : Olive pollen (Europe only)
ragweed_pollen : Ragweed pollen (Europe only)
european_aqi : European Air Quality Index
european_aqi_pm2_5 : European AQI for PM2.5
european_aqi_pm10 : European AQI for PM10
european_aqi_nitrogen_dioxide : European AQI for NO₂
european_aqi_ozone : European AQI for ozone
european_aqi_sulphur_dioxide : European AQI for SO₂
us_aqi : US Air Quality Index
us_aqi_pm2_5 : US AQI for PM2.5
us_aqi_pm10 : US AQI for PM10
us_aqi_nitrogen_dioxide : US AQI for NO₂
us_aqi_ozone : US AQI for ozone
us_aqi_sulphur_dioxide : US AQI for SO₂
us_aqi_carbon_monoxide : US AQI for CO
uv_index : UV index
uv_index_clear_sky : UV index under clear sky conditions

Marine Weather Variables

wave_height : Wave height
wave_direction : Wave direction
wave_period : Wave period
wind_wave_height : Wind wave height
swell_wave_height : Swell wave height
sea_surface_temperature : Sea surface temperature

Formatting Options

temperature_unit : celsius, fahrenheit
wind_speed_unit : kmh, ms, mph, kn
precipitation_unit : mm, inch
timezone : Europe/Paris, America/New_York, etc.

Time Range Options

forecast_days : Number of forecast days (varies by API)
past_days : Include past days data
start_date / end_date : Date range for historical data (YYYY-MM-DD format)

Development Scripts

# Development with auto-reload
npm run dev

# Build TypeScript
npm run build

# Start production server
npm start

# Run tests
npm test

# Type checking
npm run typecheck

# Linting
npm run lint

Project Structure

src/
├── index.ts          # MCP server entry point
├── client.ts         # HTTP client for Open-Meteo API
├── tools.ts          # MCP tool definitions
└── types.ts          # Zod validation schemas

API Coverage

This server provides access to all major Open-Meteo endpoints:

Weather Data

Current weather conditions
Hourly forecasts (up to 16 days)
Daily forecasts (up to 16 days)
Historical weather data (1940-present)

Specialized Models

High-resolution regional models (DWD ICON, Météo-France AROME)
Global models (NOAA GFS, ECMWF)
Regional specialists (JMA for Asia, MET Norway for Nordics)

Environmental Data

Air quality forecasts
Marine and ocean conditions
River discharge and flood warnings
Climate change projections

Advanced Features

Ensemble forecasts for uncertainty quantification
Seasonal forecasts for long-term planning
Multiple model comparison
Customizable units and timezones

Error Handling

The server provides comprehensive error handling with detailed error messages for:

Invalid coordinates
Missing required parameters
API rate limits
Network connectivity issues
Invalid date ranges

Performance

Efficient HTTP client with connection pooling
Request caching for repeated queries
Optimized data serialization
Minimal memory footprint

API Documentation

For detailed API documentation, refer to the openapi.yml file and the Open-Meteo API documentation.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

Fork the repository
Clone your fork: git clone https://github.com/your-username/open-meteo-mcp.git
Install dependencies: npm install
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Run tests: npm test
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Releasing

This project uses automated releases via GitHub Actions. To create a new release:

# For a patch release (1.0.0 -> 1.0.1)
npm run release:patch

# For a minor release (1.0.0 -> 1.1.0)
npm run release:minor

# For a major release (1.0.0 -> 2.0.0)
npm run release:major

The GitHub Action will automatically:

Run tests and build the project
Publish to npm with provenance
Create a GitHub release
Update version badges

License

MIT