open-meteo-mcp

View on GitHub

A comprehensive MCP server providing access to Open-Meteo weather APIs for Large Language Models

68 stars TypeScriptOthers Updated Sep 4, 2026

aiair-qualityclaudeclaude-codellmmcpmcp-serveropen-meteoskillsweatherweather-apiweather-forecast

Documentation

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`) - Forecasts up to 16 days (7 by default) 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 ~7 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

bash

npm install -g open-meteo-mcp-server

Method 3: From Source (Development)

bash

# 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:

json

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

Full Configuration (with environment variables)

json

{
  "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:

json

{
  "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:

json

{
  "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",
        "OPEN_METEO_CLIMATE_API_URL": "https://climate-api.example.com"
      }
    }
  }
}

Streamable HTTP Transport

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

bash

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.

> The server binds to `127.0.0.1` by default, so it is reachable only from the local machine. To accept connections from other hosts, set `HOST=0.0.0.0` explicitly. The Docker image already does this, so published ports work without extra configuration.

For production deployments, bind to a reachable interface and enable authentication and rate limiting:

bash

HOST=0.0.0.0 API_KEY=your-secret-key RATE_LIMIT_RPM=60 TRANSPORT=http PORT=3000 npx open-meteo-mcp-server

If a browser-based client connects to the server, list its origin in `ALLOWED_ORIGINS` — requests carrying an unlisted `Origin` header are rejected with `403` as DNS rebinding protection.

Clients must then include the key in every request:

code

Authorization: Bearer your-secret-key
# or
X-API-Key: your-secret-key

Using npm scripts

bash

# 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:

bash

# 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 (no `v` prefix — the git tag `v2.0.0` publishes the image as `2.0.0`):

`latest` - Latest stable release
`2.0.0` - Specific version
`2.0` - Latest 2.0.x release
`2` - Latest 2.x.x release

Using Docker Compose

The repository includes two Docker Compose configurations:

Production (uses pre-built image):

bash

# 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):

bash

# 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:

bash

# 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:

bash

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:

bash

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)
`HOST` - Interface the HTTP transport binds to (default: `127.0.0.1`, loopback only). Set to `0.0.0.0` to accept connections from other machines. The Docker image sets this to `0.0.0.0` already, so published ports work out of the box.

HTTP Transport Security (optional)

`API_KEY` - When set, all requests to `/mcp` must include this key via `Authorization: Bearer ` or `X-API-Key: `. Leave unset for open access (local/dev mode). Enforced on `GET`, `POST` and `DELETE` alike.
`RATE_LIMIT_RPM` - Maximum requests per minute per IP (default: `60`). HTTP transport only.
`TRUSTED_PROXIES` - Comma-separated list of trusted proxy IPs or CIDR ranges (e.g. `10.0.0.0/8,172.16.0.0/12`). When set, `X-Forwarded-For` is honoured only for requests originating from these addresses. Leave unset to always use the direct connection IP.
`ALLOWED_ORIGINS` - Comma-separated list of browser origins permitted to reach the server (e.g. `http://localhost:5173,https://app.example`). Protects against DNS rebinding: any request carrying an `Origin` header that is not listed is rejected with `403`. Requests without an `Origin` header — CLI clients and SDK transports — are unaffected. Empty by default.

`/health` stays reachable without a key and without rate limiting, so container probes keep working.

Skills

The `skills/` directory contains SKILL.md files that help AI assistants use this MCP server effectively. They act as contextual guides — the AI reads the relevant skill to know which tool to call and how to use its parameters.

Available skills

Skill	File	Best for
`open-meteo`	`skills/open-meteo/SKILL.md`	Everyday weather: forecasts, historical data, air quality, marine conditions, elevation
`open-meteo-advanced`	`skills/open-meteo-advanced/SKILL.md`	Specific models (ECMWF, GFS, DWD ICON…), ensemble uncertainty, seasonal outlooks, climate projections

Using with Claude Code (CLI)

Copy the skill(s) to your Claude skills directory:

bash

cp -r skills/open-meteo ~/.claude/skills/
cp -r skills/open-meteo-advanced ~/.claude/skills/

This installs them at `~/.claude/skills/open-meteo/SKILL.md` and `~/.claude/skills/open-meteo-advanced/SKILL.md`. Claude Code will load the relevant skill automatically when you ask weather-related questions.

Using with Claude Desktop

Upload the SKILL.md file directly as a document in your Claude Desktop conversation:

For everyday weather questions: upload `skills/open-meteo/SKILL.md`
For model selection, ensemble, or climate projections: upload `skills/open-meteo-advanced/SKILL.md`

Upload one skill per conversation. The AI will use it as a reference guide throughout the session.

Usage Examples

Geocoding and Location Search

code

Find the coordinates for Paris, France

code

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

code

What are the coordinates for postal code 75001?

code

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

code

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

Basic Weather Forecast

code

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

code

What were the temperatures in London during January 2023?

Air Quality Monitoring

code

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

code

Give me the current European AQI, UV index, and pollen levels (birch, grass, ragweed) in Paris.

Marine Weather

code

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

Flood Monitoring

code

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

Seasonal Forecast

code

Give me the weekly and monthly temperature outlook for Madrid over the next 4 months.

Ensemble Forecast

code

Compare the ICON and GFS ensemble forecasts for Berlin over the next 5 days and show the spread across members.

Climate Projections

code

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

bash

# 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

Evaluations

The `evals/` directory holds an LLM-usability benchmark for this server's tools — a different check than `npm test`. Unit tests verify the code is correct; this verifies that an LLM given *only* this server's tools (no other context) can actually complete realistic tasks with them.

`evals/evaluation.xml` — 10 independent, read-only question/answer pairs built on stable historical data (ERA5 archive, CMIP6 projections, geocoding, elevation), so the expected answers never change over time.
`evals/scripts/evaluation.py` — harness that launches the server, lets an agent answer each question using only its tools, and compares the answer against the expected one.

Running the evaluation

bash

npm run build
pip install -r evals/scripts/requirements.txt
export ANTHROPIC_API_KEY=your_api_key_here

npm run eval
# or directly:
python3 evals/scripts/evaluation.py -t stdio -c node -a dist/index.js evals/evaluation.xml

This calls the real Anthropic API for every question, so it consumes tokens/credits — it's a manual quality check for tool design, not part of CI.

When adding, removing, or renaming a tool, or materially changing a tool's description or schema, consider adding or updating a `qa_pair` in `evals/evaluation.xml` that exercises it.

Project Structure

code

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
├── truncation.ts     # Response size capping and serialization
└── security.ts       # Auth, origin validation, rate limiter, IP extraction

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

Response Size Limits

Tool responses are capped at 25,000 characters so a single wide query cannot overflow an LLM's context. When a response exceeds the limit, the time-series arrays (`hourly`, `daily`, `minutely_15`) are shortened by an equal ratio — keeping every parallel series aligned on the same timestamps — and two fields are added:

json

{
  "truncated": true,
  "truncation_message": "Response truncated from 95538 characters to stay within the 25000-character limit. Narrow the request (start_date/end_date, forecast_days, past_days, or fewer variables) to retrieve the full data."
}

To get complete data, narrow the request: shorter date range, fewer `forecast_days`/`past_days`, or fewer variables.

Performance

Efficient HTTP client with connection pooling
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

1. Fork the repository

2. Clone your fork: `git clone https://github.com/your-username/open-meteo-mcp.git`

3. Install dependencies: `npm install`

4. Create a feature branch: `git checkout -b feature/amazing-feature`

5. Make your changes and add tests

6. Run tests: `npm test`

7. Commit your changes: `git commit -m 'Add amazing feature'`

8. Push to the branch: `git push origin feature/amazing-feature`

9. Open a Pull Request

Releasing

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

bash

# 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

Frequently asked questions

What is open-meteo-mcp?

open-meteo-mcp is A comprehensive MCP server providing access to Open-Meteo weather APIs for Large Language Models

How do I install open-meteo-mcp?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is open-meteo-mcp open source?

Yes — it is hosted on GitHub at https://github.com/cmer81/open-meteo-mcp and has 68 stars.

Related MCP tools

Unity-MCP

AI Skills, MCP Tools, and CLI for Unity Engine. Full AI develop and test loop. Use cli for quick setup. Efficient token usage, advanced tools. Any C# method may be turned into a tool by a single line. Works with Claude Code, Gemini, Copilot, Cursor and any other absolutely for free.

4,137 C#

aiai-integrationgame-development+16

google_workspace_mcp

Control Gmail, Google Calendar, Docs, Sheets, Slides, Chat, Forms, Tasks, Search & Drive with AI - Comprehensive Google Workspace MCP Server & CLI Tool

3,117 Python

aigmailgoogle-calendar+17

wigolo

The go-to web for your AI coding agent — local-first search, fetch, crawl & research over MCP. No API keys, no cloud, $0/query. Public beta.

4,906 TypeScript

mcpagentai+17

mcp

Official Microsoft Learn MCP Server and CLI tool – powering LLMs and AI agents with real-time, trusted Microsoft docs & code samples.

1,872 TypeScript

aiai-agentsdocumentation+9

codesight

Universal AI context generator. Saves thousands of tokens per conversation in Claude Code, Cursor, Copilot, Codex, and more.

1,397 TypeScript

aiclaudecli+11

tuui

A desktop MCP client designed as a tool unitary utility integration, accelerating AI adoption through the Model Context Protocol (MCP) and enabling cross-vendor LLM API orchestration.

1,153 TypeScript

agentagentic-aiai+17

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP