chuk-mcp-open-meteo
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@chuk-mcp-open-meteo get the current weather in Tokyo"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Chuk MCP Open-Meteo
The best weather MCP server ever - A comprehensive Model Context Protocol (MCP) server for accessing Open-Meteo weather data.
This is a demonstration project provided as-is for learning and testing purposes.
Features
This MCP server provides comprehensive access to Open-Meteo's weather APIs through 12 tools — 6 single-location tools and 6 batch tools for multi-location queries.
All tools return fully-typed Pydantic v2 models for type safety, validation, and excellent IDE support. Every model includes rich, LLM-friendly field descriptions with interpretation guides for better AI understanding.
Single-Location Tools
1. Weather Forecast (get_weather_forecast)
Get detailed weather forecasts with customizable parameters:
Current weather conditions
Hourly forecasts (up to 16 days)
Daily forecasts
50+ weather variables including temperature, precipitation, wind, humidity, cloud cover, and more
Multiple units (celsius/fahrenheit, km/h, mph, m/s, knots)
Automatic timezone detection
2. Location Geocoding (geocode_location)
Convert location names to coordinates:
Search for any location worldwide
Get coordinates, elevation, timezone
Country and administrative information
Population data where available
Multi-language support
3. Historical Weather (get_historical_weather)
Access historical weather data:
Data from 1940 onwards (location-dependent)
Same comprehensive variables as forecasts
Perfect for climate analysis and trends
Hourly and daily aggregations
4. Air Quality (get_air_quality)
Monitor air quality and pollutants:
PM2.5, PM10 particulate matter
CO, NO2, SO2, O3 gas concentrations
European AQI and US AQI indices
Pollen data (multiple species)
UV index
Aerosol optical depth
5. Marine Forecast (get_marine_forecast)
Get marine weather conditions:
Wave height, direction, and period
Wind waves and swell waves separately
Ocean current velocity and direction
Up to 16-day forecasts
Essential for maritime activities
Field descriptions include wave quality interpretations (0-0.5m calm, 1.5-2.5m moderate, etc.)
6. Weather Code Interpretation (interpret_weather_code)
Translate numeric weather codes to descriptions:
Converts WMO weather codes (0-99) to human-readable text
Includes severity categories (clear, rain, snow, thunderstorm, etc.)
Helps LLMs explain weather conditions in natural language
Built-in reference for all standard weather codes
Batch Tools
Batch tools dramatically reduce latency when querying multiple locations. Instead of N sequential tool calls (~3 minutes for 20 cities), batch tools complete in a single call (~0.3–0.5 seconds).
7. Batch Geocoding (batch_geocode_locations)
Geocode multiple location names concurrently:
Comma-separated input:
"London,Paris,Berlin,Madrid,Rome"Concurrent execution with connection pooling
Partial failure handling — individual locations can fail without breaking the batch
Results in same order as input
8. Batch Weather Forecasts (batch_get_weather_forecasts)
Fetch forecasts for up to 1000 locations in a single API call:
Uses Open-Meteo's native multi-location support
Single HTTP request for all locations
Same parameters as
get_weather_forecast
9. Batch Air Quality (batch_get_air_quality)
Air quality data for multiple locations in one API call:
Compare pollution levels across cities
Defaults to common pollutant metrics (PM2.5, PM10, AQI, etc.)
10. Batch Marine Forecasts (batch_get_marine_forecasts)
Marine conditions for multiple coastal points in one API call:
Compare surf spots, monitor coastline conditions
Waves, swell, currents, and tides across locations
11. Batch Historical Weather (batch_get_historical_weather)
Historical data for multiple locations in one API call:
All locations share the same date range
Useful for climate comparisons across cities
12. Batch Weather Code Interpretation (batch_interpret_weather_codes)
Interpret multiple WMO weather codes in a single call:
Comma-separated input:
"3,51,61,95"Eliminates multiple sequential
interpret_weather_codecallsIdeal after batch forecasts return different codes per location
Recommended Batch Workflow
1. batch_geocode_locations("London,Paris,Berlin") → coordinates
2. batch_get_weather_forecasts(latitudes="51.51,48.86,52.52", longitudes="-0.13,2.35,13.41") → weather
3. batch_interpret_weather_codes("3,51,61") → descriptionsRelated MCP server: Open-Meteo MCP Server
Installation
Using uvx (Recommended - No Installation Required!)
The easiest way to use the server is with uvx, which runs it without installing:
uvx chuk-mcp-open-meteoThis automatically downloads and runs the latest version. Perfect for Claude Desktop!
Using uv (Recommended for Development)
# Install from PyPI
uv pip install chuk-mcp-open-meteo
# Or clone and install from source
git clone <repository-url>
cd chuk-mcp-open-meteo
uv sync --devUsing pip (Traditional)
pip install chuk-mcp-open-meteoUsage
With Claude Desktop
Option 1: Use the Public Server (Easiest)
Connect to the hosted public server at weather.chukai.io:
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"weather": {
"url": "https://weather.chukai.io/mcp"
}
}
}Option 2: Run Locally with uvx
{
"mcpServers": {
"open-meteo": {
"command": "uvx",
"args": ["chuk-mcp-open-meteo"]
}
}
}Option 3: Run Locally with pip
{
"mcpServers": {
"open-meteo": {
"command": "chuk-mcp-open-meteo"
}
}
}Standalone
Run the server directly:
# With uvx (recommended - always latest version)
uvx chuk-mcp-open-meteo
# With uvx in HTTP mode
uvx chuk-mcp-open-meteo http
# Or if installed locally
chuk-mcp-open-meteo
chuk-mcp-open-meteo httpOr with uv/Python:
# STDIO mode (default, for MCP clients)
uv run chuk-mcp-open-meteo
# or: python -m chuk_mcp_open_meteo.server
# HTTP mode (for web access)
uv run chuk-mcp-open-meteo http
# or: python -m chuk_mcp_open_meteo.server httpSTDIO mode is for MCP clients like Claude Desktop and mcp-cli. HTTP mode runs a web server on http://localhost:8000 for HTTP-based MCP clients.
Example Usage
Once configured, you can ask Claude questions like:
"What's the current weather in London?"
"Give me a 7-day forecast for Tokyo with hourly temperature and precipitation"
"What was the weather like in New York on July 4th, 2020?"
"What's the air quality in Los Angeles right now?"
"What are the wave conditions off the coast of Hawaii?"
"Find the coordinates for Paris, France"
Python Examples
Check out the examples/ directory for runnable Python examples:
# With uv (recommended)
uv run python examples/example_basic.py
uv run python examples/example_trip_planner.py
uv run python examples/test_mcp_protocol.py
# Or with plain python (if installed)
python examples/example_basic.py
python examples/example_trip_planner.py
python examples/test_mcp_protocol.py
# Run all examples
./examples/test_all.shSee examples/README.md for detailed documentation.
Tool Reference
All tools return Pydantic v2 models with full type safety. When calling from Python, you get clean object access:
from chuk_mcp_open_meteo.server import get_weather_forecast
# Get weather forecast
forecast = await get_weather_forecast(latitude=51.5072, longitude=-0.1276, current_weather=True)
# Access data via typed attributes (not dictionaries!)
if forecast.current_weather:
temp = forecast.current_weather.temperature # Type-safe access
wind = forecast.current_weather.windspeedget_weather_forecast
Parameters:
{
"latitude": 51.5072,
"longitude": -0.1276,
"temperature_unit": "celsius", # or "fahrenheit"
"wind_speed_unit": "kmh", # or "ms", "mph", "kn"
"precipitation_unit": "mm", # or "inch"
"timezone": "auto", # or specific timezone
"forecast_days": 7, # 1-16
"current_weather": true,
"hourly": "temperature_2m,precipitation,wind_speed_10m",
"daily": "temperature_2m_max,temperature_2m_min,precipitation_sum"
}Returns: WeatherForecast Pydantic model
Popular hourly variables: temperature_2m, relative_humidity_2m, precipitation, rain, snowfall, cloud_cover, wind_speed_10m, wind_direction_10m, pressure_msl, visibility
Popular daily variables: temperature_2m_max, temperature_2m_min, precipitation_sum, rain_sum, sunrise, sunset, wind_speed_10m_max
geocode_location
Parameters:
{
"name": "London",
"count": 10, # number of results
"language": "en" # language code
}Returns: GeocodingResponse Pydantic model
get_historical_weather
Parameters:
{
"latitude": 40.7128,
"longitude": -74.0060,
"start_date": "2020-01-01",
"end_date": "2020-01-31",
"hourly": "temperature_2m,precipitation",
"daily": "temperature_2m_max,temperature_2m_min"
}Returns: HistoricalWeather Pydantic model
get_air_quality
Parameters:
{
"latitude": 34.0522,
"longitude": -118.2437,
"hourly": "pm10,pm2_5,us_aqi,european_aqi"
}Returns: AirQualityResponse Pydantic model
get_marine_forecast
Parameters:
{
"latitude": 21.3099,
"longitude": -157.8581,
"hourly": "wave_height,wave_direction,wave_period"
}Returns: MarineForecast Pydantic model
Development
Setup
# Clone the repository
git clone <repository-url>
cd chuk-mcp-open-meteo
# Install with uv (recommended)
uv sync --dev
# Or with pip
pip install -e ".[dev]"Running Tests
make test # Run tests (excludes network tests)
make test-cov # Run tests with coverage
make coverage-report # Show coverage report
# Run all tests including network tests (requires internet)
pytest tests/ # Run all 40 tests
pytest tests/ -m network # Run only network testsNote: Network tests make real API calls to Open-Meteo and are excluded from CI to avoid flaky builds. They include automatic retry logic for local development.
Code Quality
make lint # Run linters
make format # Auto-format code
make typecheck # Run type checking
make security # Run security checks
make check # Run all checksBuilding
make build # Build package
make docker-build # Build Docker imageDeployment
Fly.io
Deploy to Fly.io with a single command:
# First time setup
fly launch
# Deploy updates
fly deployThe server will be available via HTTP at your Fly.io URL.
Docker
# Build the image
docker build -t chuk-mcp-open-meteo .
# Run the container
docker run -p 8000:8000 chuk-mcp-open-meteoAPI Credits
This server uses the free Open-Meteo API. Open-Meteo provides:
Free access for non-commercial use
No API key required
High-resolution weather models
25+ global weather models
Historical data from 1940
No rate limits for reasonable use
Please consider supporting Open-Meteo if you use this extensively.
Architecture
Built on top of chuk-mcp-server, this server uses a modular architecture:
src/chuk_mcp_open_meteo/
├── server.py # Thin entry point — imports tools, runs server
├── models.py # All Pydantic v2 response models (26 models)
├── _constants.py # API URLs, default parameters, weather codes
├── _batch.py # Generic batch fetch helper (DRY across 4 batch tools)
└── tools/ # Domain-focused tool modules
├── forecast.py # get_weather_forecast + batch_get_weather_forecasts
├── geocoding.py # geocode_location + batch_geocode_locations
├── historical.py # get_historical_weather + batch_get_historical_weather
├── air_quality.py # get_air_quality + batch_get_air_quality
├── marine.py # get_marine_forecast + batch_get_marine_forecasts
└── weather_codes.py # interpret_weather_codeDesign principles:
Async Native: All tools are async/await, all HTTP via httpx.AsyncClient
Pydantic Native: All responses use Pydantic v2 models for validation and type safety
No Magic Strings: API URLs and default parameters are named constants
Composable Modules: Each domain is a self-contained module with single and batch tools
Type-Safe: Automatic JSON-RPC schema generation from Python type hints
LLM-Optimized: Rich field descriptions with interpretation guides embedded in models
Wave heights include size categories (calm/small/moderate/large/dangerous)
Wave periods include quality ratings (choppy/good/excellent)
Weather codes include quick reference in field descriptions
Direction fields explain meteorological conventions
All measurements include context and safety thresholds
High Performance: Sub-3ms latency, 36,000+ RPS capability
Public Server
A public instance is hosted at weather.chukai.io for easy access:
URL:
https://weather.chukai.io/mcpProtocol: MCP over HTTPS
Free to use: No API key required
Always up-to-date: Running the latest version
Simply add it to your Claude Desktop config:
{
"mcpServers": {
"weather": {
"url": "https://weather.chukai.io/mcp"
}
}
}Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Fork the repository
Create your feature branch (
git checkout -b feature/amazing-feature)Commit your changes (
git commit -m 'Add amazing feature')Push to the branch (
git push origin feature/amazing-feature)Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
Open-Meteo for providing excellent free weather data
Model Context Protocol for the MCP specification
Anthropic for Claude and MCP support
License
Apache License 2.0 - See LICENSE for details.
Documentation
Available Tools
12 toolsbatch_geocode_locationsA
Geocode multiple location names to coordinates in a single call.
Use this tool instead of calling geocode_location repeatedly when you need coordinates for multiple locations (e.g., "weather across the UK", "compare temperatures in European capitals").
This tool makes all geocoding requests concurrently, dramatically reducing latency compared to sequential calls. For N locations, this completes in roughly the time of 1 request instead of N sequential requests.
Args: names: Comma-separated list of location names to geocode. Examples: - "London,Paris,Berlin,Madrid,Rome" - "New York,Los Angeles,Chicago,Houston" - "Tokyo,Seoul,Beijing,Shanghai" Each name is searched independently. Whitespace around commas is trimmed. Maximum recommended: 50 locations per call. count: Maximum number of results per location (1-10). Default is 1. Use 1 when you know the exact locations (most common for batch). Use 3-5 for ambiguous names where you need to pick the right match. language: Language code for result names. Default is "en".
Returns: BatchGeocodingResponse: Contains: - results: List of BatchGeocodingItem, one per input location, in order. Each item has: query (original name), found (bool), results (list), error (str or None) - total_queries: How many locations were searched - successful: How many returned results - failed: How many returned no results or had errors
Tips for LLMs: - Use this FIRST when a user asks about weather in multiple places - After getting coordinates, pass them to batch_get_weather_forecasts - Partial failures are normal - some location names may not be found - Check the 'found' field on each item to identify failures - For failed items, try simpler search terms (just city name without region) - The results are in the SAME ORDER as the input names
Example: # Geocode 5 UK cities at once batch = await batch_geocode_locations("London,Manchester,Edinburgh,Cardiff,Belfast") # Extract coordinates for found locations coords = [(r.results[0].latitude, r.results[0].longitude) for r in batch.results if r.found]
Inputs: names (required), count, language.
batch_get_air_qualityA
Get air quality data for multiple locations in a single API call.
This tool uses Open-Meteo's native batch support to fetch air quality data for many locations at once. Useful for comparing pollution levels across cities.
Args: latitudes: Comma-separated latitude values for all locations. Example: "51.51,48.86,52.52" Must have the same number of values as longitudes. longitudes: Comma-separated longitude values for all locations. Example: "-0.13,2.35,13.41" Must have the same number of values as latitudes. timezone: Timezone name or "auto" for automatic detection per location hourly: Comma-separated air quality variables. If not provided, defaults to: pm10, pm2_5, carbon_monoxide, nitrogen_dioxide, sulphur_dioxide, ozone, us_aqi, european_aqi domains: Model domain - "auto" (default), "cams_global", "cams_europe"
Returns: BatchAirQualityResponse: Contains: - results: List of BatchAirQualityItem, each with location_index and air_quality - total_locations: Number of locations queried
Tips for LLMs: - Use batch_geocode_locations first to get coordinates - Results are in the SAME ORDER as the input coordinates - Useful for "compare air quality across cities" queries - All locations share the same hourly variables and domain settings
Example: # Compare air quality across 3 cities result = await batch_get_air_quality( latitudes="51.51,48.86,34.05", longitudes="-0.13,2.35,-118.24", hourly="pm2_5,us_aqi" ) for item in result.results: aqi = item.air_quality.hourly.us_aqi[0] print(f"Location {item.location_index}: AQI {aqi}")
Inputs: latitudes (required), longitudes (required), hourly, domains, +1 more.
batch_get_historical_weatherA
Get historical weather data for multiple locations in a single API call.
This tool uses Open-Meteo's native batch support to fetch historical weather for many locations at once. All locations share the same date range.
Args: latitudes: Comma-separated latitude values for all locations. Example: "51.51,48.86,52.52" Must have the same number of values as longitudes. longitudes: Comma-separated longitude values for all locations. Example: "-0.13,2.35,13.41" Must have the same number of values as latitudes. start_date: Start date in YYYY-MM-DD format (shared across all locations) end_date: End date in YYYY-MM-DD format (shared across all locations) temperature_unit: Temperature unit - "celsius" (default) or "fahrenheit" wind_speed_unit: Wind speed unit - "kmh" (default), "ms", "mph", "kn" precipitation_unit: Precipitation unit - "mm" (default) or "inch" timezone: Timezone name or "auto" for automatic detection per location hourly: Comma-separated hourly variables (same as get_historical_weather). daily: Comma-separated daily variables (same as get_historical_weather).
Returns: BatchHistoricalWeatherResponse: Contains: - results: List of BatchHistoricalWeatherItem, each with location_index and weather - total_locations: Number of locations queried
Tips for LLMs: - Use batch_geocode_locations first to get coordinates - All locations share the same date range - if you need different dates per location, use separate get_historical_weather calls - Results are in the SAME ORDER as the input coordinates - Useful for climate comparisons across cities for the same time period
Example: # Compare last week's weather across European capitals result = await batch_get_historical_weather( latitudes="51.51,48.86,52.52", longitudes="-0.13,2.35,13.41", start_date="2025-01-01", end_date="2025-01-07", daily="temperature_2m_max,temperature_2m_min,precipitation_sum" )
Inputs: end_date (required), latitudes (required), longitudes (required), start_date (required), +6 more.
batch_get_marine_forecastsA
Get marine forecasts for multiple coastal locations in a single API call.
This tool uses Open-Meteo's native batch support to fetch marine conditions for many locations at once. Useful for comparing surf spots, planning coastal trips, or monitoring conditions along a coastline.
Args: latitudes: Comma-separated latitude values for all locations. Example: "21.31,33.87,36.97" (Honolulu, San Diego, Monterey) Must be over ocean/coastal areas. Same count as longitudes. longitudes: Comma-separated longitude values for all locations. Example: "-157.86,-118.29,-122.00" Must be over ocean/coastal areas. Same count as latitudes. timezone: Timezone name or "auto" for automatic detection per location hourly: Comma-separated hourly marine variables. If not provided, defaults to: wave_height, wave_direction, wave_period, wind_wave_height, swell_wave_height, sea_level_height_msl daily: Comma-separated daily marine variables (e.g., wave_height_max, wave_direction_dominant) forecast_days: Number of forecast days (1-16). Default is 7.
Returns: BatchMarineForecastResponse: Contains: - results: List of BatchMarineForecastItem, each with location_index and forecast - total_locations: Number of locations queried
Tips for LLMs: - Use batch_geocode_locations first to get coordinates for coastal cities - Results are in the SAME ORDER as the input coordinates - Useful for "compare surf conditions" or "wave heights along the coast" queries - All locations share the same hourly/daily variables and forecast_days - Coordinates must be over ocean/coastal areas (inland locations will fail)
Example: # Compare surf conditions at 3 beaches result = await batch_get_marine_forecasts( latitudes="21.31,33.87,36.97", longitudes="-157.86,-118.29,-122.00", hourly="wave_height,wave_period,swell_wave_height", forecast_days=3 ) for item in result.results: waves = item.forecast.hourly.wave_height[0] print(f"Location {item.location_index}: {waves}m waves")
Inputs: latitudes (required), longitudes (required), daily, hourly, +2 more.
batch_get_weather_forecastsA
Get weather forecasts for multiple locations in a single API call.
This tool uses Open-Meteo's native batch support to fetch forecasts for up to 1000 locations in ONE HTTP request. This is dramatically faster than calling get_weather_forecast repeatedly.
Use batch_geocode_locations first to get coordinates, then pass them here.
Args: latitudes: Comma-separated latitude values for all locations. Example: "51.51,48.86,52.52" (London, Paris, Berlin) Must have the same number of values as longitudes. longitudes: Comma-separated longitude values for all locations. Example: "-0.13,2.35,13.41" (London, Paris, Berlin) Must have the same number of values as latitudes. temperature_unit: Temperature unit - "celsius" (default) or "fahrenheit" wind_speed_unit: Wind speed unit - "kmh" (default), "ms", "mph", "kn" precipitation_unit: Precipitation unit - "mm" (default) or "inch" timezone: Timezone name or "auto" for automatic detection per location forecast_days: Number of forecast days (1-16). Default is 7. current_weather: Include current weather conditions. Default is True. hourly: Comma-separated hourly variables (same as get_weather_forecast). Popular: temperature_2m, precipitation, wind_speed_10m, cloud_cover daily: Comma-separated daily variables (same as get_weather_forecast). Popular: temperature_2m_max, temperature_2m_min, precipitation_sum
Returns: BatchWeatherForecastResponse: Contains: - results: List of BatchWeatherForecastItem, each with location_index and forecast - total_locations: Number of locations queried
Tips for LLMs: - ALWAYS use batch_geocode_locations first to get coordinates - The forecasts are returned in the SAME ORDER as the input coordinates - All locations share the same forecast parameters (hourly, daily, units) - For different parameters per location, make separate get_weather_forecast calls - Maximum ~1000 locations per call (Open-Meteo API limit) - The latitudes and longitudes strings must have equal numbers of comma-separated values
Workflow for "What's the weather across the UK?": 1. batch_geocode_locations("London,Manchester,Edinburgh,Cardiff,Belfast,Birmingham") 2. Extract latitudes and longitudes from successful results 3. batch_get_weather_forecasts(latitudes="51.51,53.48,55.95,...", longitudes="-0.13,-2.24,-3.19,...") 4. Present the weather comparison to the user
Example: # Get weather for London, Paris, and Berlin forecasts = await batch_get_weather_forecasts( latitudes="51.51,48.86,52.52", longitudes="-0.13,2.35,13.41", current_weather=True, daily="temperature_2m_max,temperature_2m_min,precipitation_sum" ) for item in forecasts.results: f = item.forecast print(f"Location {item.location_index}: {f.current_weather.temperature}C")
Inputs: latitudes (required), longitudes (required), daily, hourly, +6 more.
batch_interpret_weather_codesA
Interpret multiple WMO weather codes in a single call.
Instead of calling interpret_weather_code multiple times (one per code), pass all codes at once. This is much more efficient when processing weather data for multiple locations.
Args: weather_codes: Comma-separated WMO weather code integers (0-99). Example: "3,51,61,95" or "0, 3, 45, 80"
Returns: BatchWeatherCodeResponse: Pydantic model with: - results: List of interpretations in same order as input (each includes an icon URL) - total_codes: Number of codes processed
Map icon tip:
Each result includes an icon field — a PNG URL for the weather condition.
When building a GeoJSON FeatureCollection for a map, put each result's icon
in the corresponding feature's properties.icon so the map shows weather
icons instead of default blue pins.
Example: # After batch forecast returns codes for multiple cities: result = await batch_interpret_weather_codes("3,51,61,95") # Returns all interpretations in one call instead of 4 separate calls
Inputs: weather_codes (required).
geocode_locationA
Convert location names to coordinates and get detailed geographic information.
Use this tool FIRST before calling weather tools to get accurate coordinates for any location. Searches worldwide database of cities, towns, and places with comprehensive metadata.
Args: name: Location name to search for. Can be: - City name: "London", "Tokyo", "New York" - City with country: "Paris, France", "Portland, Oregon" - Region or landmark: "Cornwall", "Lake Tahoe" - Address or place: "Times Square", "Big Ben" count: Maximum number of results to return (1-100). Default is 10. Use 1 if you're confident about the location (e.g., "London, UK") Use 5-10 for ambiguous names (e.g., "Paris" - could be France, Texas, etc.) language: Language code for result names. Options: "en" (English, default), "de" (German), "fr" (French), "es" (Spanish), "it" (Italian), "pt" (Portuguese), etc. format: Response format. Always use "json" (default).
Returns: GeocodingResponse: A Pydantic model containing: - results: List of matching locations, each with: - name: Location name - latitude, longitude: Coordinates (use these for weather tools!) - country, country_code: Country information - timezone: IANA timezone (e.g., "Europe/London") - elevation: Meters above sea level - population: Population (if available) - admin1, admin2: Administrative divisions (state, county, etc.) - feature_code: Type of place (PPLC=capital, PPL=populated place, etc.)
Tips for LLMs: - ALWAYS geocode location names before requesting weather data - Results are sorted by relevance (population, importance) - First result is usually what users mean for well-known cities - For ambiguous names, check country/admin divisions to pick the right one - Use the exact latitude/longitude from results in weather API calls - Timezone from geocoding can be passed to weather APIs for local time - CRITICAL: If no results found, IMMEDIATELY retry with simpler search terms! The API works best with just city names (e.g., "Portland" not "Portland Harbor" or "Portland, Maine") WORKFLOW: If "City, Region" fails → AUTOMATICALLY try just "City" → filter by admin1/admin2/country DO NOT ask the user - just retry automatically with the simpler name! - If still no results after retry: try even simpler terms or use nearest known location - Common pattern: "Harbor Name" fails → retry just the city name → filter by region/country
Example: # Find London coordinates locations = await geocode_location("London", count=1) london = locations.results[0] # Use coordinates for weather: london.latitude, london.longitude
# Handle ambiguous names
locations = await geocode_location("Paris", count=5)
# results[0] = Paris, France (population 2.1M)
# results[1] = Paris, Texas (population 25K)
# Pick based on context or ask user
# If "City, Region" returns no results, try just "City"
locations = await geocode_location("Portland, Maine", count=5)
if not locations.results:
# Try simpler search
locations = await geocode_location("Portland", count=5)
# Filter by country_code='US' and admin1='Maine' to get the right one
portland = next(r for r in locations.results if r.country_code == 'US' and r.admin1 == 'Maine')
Inputs: name (required), count, format, language.
get_air_qualityB
Get air quality data and forecasts from Open-Meteo Air Quality API.
Args: latitude: Latitude coordinate (-90 to 90) longitude: Longitude coordinate (-180 to 180) timezone: Timezone (e.g., 'America/New_York', 'auto' for automatic) hourly: Comma-separated air quality variables domains: Model domain - auto, cams_global, cams_europe
Returns: AirQualityResponse: Pydantic model with air quality data
Example: air = await get_air_quality(34.0522, -118.2437) if air.hourly and air.hourly.us_aqi: aqi = air.hourly.us_aqi[0] print(f"US AQI: {aqi}")
Inputs: latitude (required), longitude (required), hourly, domains, +1 more.
get_historical_weatherA
Get historical weather data from Open-Meteo Archive API.
Args: latitude: Latitude coordinate (-90 to 90) longitude: Longitude coordinate (-180 to 180) start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format temperature_unit: Temperature unit - celsius, fahrenheit wind_speed_unit: Wind speed unit - kmh, ms, mph, kn precipitation_unit: Precipitation unit - mm, inch timezone: Timezone (e.g., 'America/New_York', 'auto' for automatic) hourly: Comma-separated hourly variables daily: Comma-separated daily variables
Returns: HistoricalWeather: Pydantic model with historical data
Example: historical = await get_historical_weather( 48.8566, 2.3522, "2024-01-01", "2024-01-07", daily="temperature_2m_max,temperature_2m_min" ) avg_high = sum(historical.daily.temperature_2m_max) / len(historical.daily.temperature_2m_max)
Inputs: end_date (required), latitude (required), longitude (required), start_date (required), +6 more.
get_marine_forecastA
Get ocean and marine weather forecasts including waves, swell, currents, and TIDES.
PRIMARY USE FOR TIDES: This tool provides tidal height predictions via the 'sea_level_height_msl' variable. Use this when users ask about tide times, high/low tides, or tide heights for coastal locations.
Also use this for maritime activities, surfing, sailing, fishing, or beach conditions. Provides detailed wave forecasts from multiple global ocean models.
Args: latitude: Latitude coordinate in decimal degrees (-90 to 90). Must be over ocean/coastal areas. Use geocode_location to find coordinates for coastal cities and beaches. longitude: Longitude coordinate in decimal degrees (-180 to 180). Must be over ocean/coastal areas. timezone: Timezone name (e.g., "Pacific/Auckland", "Europe/London") or "auto" for automatic hourly: Comma-separated list of hourly marine variables. Popular options: Wave characteristics (total): - wave_height: Significant wave height in meters (combined wind + swell) - wave_direction: Wave direction in degrees (0-360, meteorological convention) - wave_period: Wave period in seconds
Wind waves (locally generated):
- wind_wave_height: Wind wave height in meters
- wind_wave_direction: Wind wave direction in degrees
- wind_wave_period: Wind wave period in seconds
- wind_wave_peak_period: Peak period of wind waves
Swell waves (distant storms):
- swell_wave_height: Swell wave height in meters
- swell_wave_direction: Swell wave direction in degrees
- swell_wave_period: Swell wave period in seconds
- swell_wave_peak_period: Peak period of swell
Ocean currents:
- ocean_current_velocity: Current speed in m/s
- ocean_current_direction: Current direction in degrees
Tides (IMPORTANT for tide predictions):
- sea_level_height_msl: Sea level height in meters (includes tides - shows clear tidal cycles)
Other useful variables:
- sea_surface_temperature: Water temperature in °C
NOTE: Do NOT include regular weather variables like 'wind_speed', 'temperature',
'precipitation' - those come from get_weather_forecast, not marine API!
daily: Comma-separated list of daily marine variables. Options:
- wave_height_max: Maximum wave height for the day
- wave_direction_dominant: Dominant wave direction
- wave_period_max: Maximum wave period
forecast_days: Number of forecast days (1-16). Default is 7.Returns: MarineForecast: A Pydantic model containing: - latitude, longitude: Actual coordinates used (may be adjusted to nearest ocean grid point) - hourly: Hourly marine forecast data (wave heights, directions, periods, currents) - daily: Daily marine forecast data (if requested) - timezone: Timezone information
Tips for LLMs: - TIDE QUERIES: When user asks "what are the tide times" or "when is high/low tide": 1. Use geocode_location to get coordinates (try just city name if "City, Region" fails) 2. Call this tool with hourly="sea_level_height_msl" immediately (don't ask for clarification first!) 3. Analyze the sea_level_height_msl values to find peaks (high tide) and troughs (low tide) 4. Present the times and heights to the user Example: "High tide at 05:00 (+1.63m), Low tide at 12:00 (-2.17m)" - Use this for surfing, sailing, boating, fishing, beach safety questions - wave_height is the key metric - measured in meters: * 0-0.5m: Calm, good for swimming * 0.5-1.5m: Small waves, beginner surfing * 1.5-2.5m: Moderate waves, intermediate surfing * 2.5-4m: Large waves, advanced surfing * 4m+: Very large, dangerous for most activities - wave_period (seconds) indicates wave quality for surfing: * <8s: Short period, choppy (wind waves) * 8-12s: Medium period, good surf * 12s+: Long period, excellent surf (swell) - Combine with get_weather_forecast for complete marine conditions (wind, visibility, storms) - For surfing: need wave_height (size), wave_period (quality), and local wind (from weather forecast) - swell_wave data shows waves from distant storms (clean, organized) - wind_wave data shows local wind-generated waves (choppy if strong winds) - ocean_current data important for safety and navigation
Common use cases: - Tide predictions: Use sea_level_height_msl to find high/low tide times and heights - Surfing: Check wave_height, wave_period, swell_wave_height, and sea_level_height_msl (tides affect wave quality) - Swimming safety: Check wave_height (stay <1m for safety) and sea_level_height_msl (avoid swimming during strong tidal currents) - Sailing/boating: Check wave_height, wave_period, ocean_current_velocity, and sea_level_height_msl (for harbor entry/exit timing) - Fishing: Check ocean_current, sea_surface_temperature, and sea_level_height_msl (fish feeding patterns follow tides) - Beach conditions: Check wave_height, sea_level_height_msl, and combine with weather forecast (wind, rain)
Example: # Get tide times and heights for a coastal location marine = await get_marine_forecast( 51.5074, -0.1278, # Example coordinates (coastal UK) hourly="sea_level_height_msl", timezone="Europe/London", forecast_days=1 ) # Find high and low tides by analyzing sea_level_height_msl values # High tide = maximum values (e.g., +1.5m), Low tide = minimum values (e.g., -2.0m) # Tidal cycle repeats approximately every 12 hours (two highs and two lows per day)
# Get surf conditions for Hawaii (including tides)
marine = await get_marine_forecast(
21.3099, -157.8581, # Honolulu coordinates
hourly="wave_height,wave_period,swell_wave_height,swell_wave_direction,sea_level_height_msl",
forecast_days=3
)
current_wave_height = marine.hourly.wave_height[0]
current_period = marine.hourly.wave_period[0]
current_tide = marine.hourly.sea_level_height_msl[0]
# Check if good for surfing
if 1.5 <= current_wave_height <= 3.0 and current_period >= 10:
print("Good surf conditions!")
# Get daily max waves for trip planning
marine = await get_marine_forecast(
lat, lon,
daily="wave_height_max,wave_direction_dominant",
forecast_days=7
)
Inputs: latitude (required), longitude (required), daily, hourly, +2 more.
get_weather_forecastA
Get comprehensive weather forecast with current conditions, hourly, and daily forecasts.
This tool provides detailed weather forecasts from Open-Meteo API with 50+ weather variables. Use this for answering questions about current weather, future forecasts, or detailed conditions.
Args: latitude: Latitude coordinate in decimal degrees (-90 to 90). Use geocode_location to find coordinates. longitude: Longitude coordinate in decimal degrees (-180 to 180). Use geocode_location to find coordinates. temperature_unit: Temperature unit. Options: "celsius" (default), "fahrenheit" wind_speed_unit: Wind speed unit. Options: "kmh" (default), "ms", "mph", "kn" precipitation_unit: Precipitation unit. Options: "mm" (default), "inch" timezone: Timezone name (e.g., "America/New_York", "Europe/London") or "auto" for automatic detection forecast_days: Number of forecast days (1-16). Default is 7. current_weather: Set to True to include current weather conditions (recommended) hourly: Comma-separated list of hourly variables. Popular options: - temperature_2m: Temperature at 2m height - precipitation: Total precipitation (rain + snow) - rain: Rain only - snowfall: Snowfall amount - cloud_cover: Cloud cover percentage (0-100) - wind_speed_10m, wind_direction_10m: Wind at 10m height - relative_humidity_2m: Relative humidity - pressure_msl: Sea level pressure - visibility: Visibility distance - uv_index: UV index daily: Comma-separated list of daily variables. Popular options: - temperature_2m_max, temperature_2m_min: Daily temperature range - precipitation_sum: Total daily precipitation - rain_sum: Total daily rain - sunrise, sunset: Sun times - wind_speed_10m_max: Maximum daily wind speed - precipitation_hours: Hours with precipitation
Returns: WeatherForecast: A Pydantic model containing: - latitude, longitude: Actual coordinates used - current_weather: Current conditions (temperature, wind, weather code) - hourly: Hourly forecast data (if requested) - daily: Daily forecast data (if requested) - timezone: Timezone information
Tips for LLMs: - Always use current_weather=True for "what's the weather" questions - Request hourly data for detailed forecasts (e.g., "hourly rain predictions") - Request daily data for multi-day forecasts (e.g., "week ahead") - Weather codes: 0=clear, 1-3=partly cloudy, 45/48=fog, 51-57=drizzle, 61-67=rain, 71-77=snow, 80-82=rain showers, 95-99=thunderstorm
Example: # Get current weather for London forecast = await get_weather_forecast(51.5072, -0.1276, current_weather=True) temp = forecast.current_weather.temperature
# Get detailed 3-day forecast with hourly data
forecast = await get_weather_forecast(
51.5072, -0.1276,
forecast_days=3,
hourly="temperature_2m,precipitation,wind_speed_10m",
daily="temperature_2m_max,temperature_2m_min,precipitation_sum"
)
Inputs: latitude (required), longitude (required), daily, hourly, +6 more.
interpret_weather_codeA
Interpret WMO weather codes used by Open-Meteo API.
Weather codes are numerical values (0-99) that represent different weather conditions. This tool translates codes into human-readable descriptions.
Args: weather_code: WMO weather code integer (0-99) from weather forecast data. This is the 'weathercode' field in current_weather or hourly/daily data.
Returns: WeatherCodeInterpretation: Pydantic model with: - code: The weather code number - description: Human-readable weather condition - severity: Category (clear, cloudy, fog, drizzle, rain, freezing, snow, showers, thunderstorm)
Common Weather Codes: Clear/Cloudy (0-3): 0 = Clear sky 1 = Mainly clear 2 = Partly cloudy 3 = Overcast
Fog (45-48):
45 = Fog
48 = Depositing rime fog
Drizzle (51-57):
51 = Light drizzle
53 = Moderate drizzle
55 = Dense drizzle
56-57 = Freezing drizzle
Rain (61-67):
61 = Slight rain
63 = Moderate rain
65 = Heavy rain
66-67 = Freezing rain
Snow (71-77, 85-86):
71 = Slight snow
73 = Moderate snow
75 = Heavy snow
77 = Snow grains
85-86 = Snow showers
Showers (80-82):
80 = Slight rain showers
81 = Moderate rain showers
82 = Violent rain showers
Thunderstorm (95-99):
95 = Thunderstorm
96 = Thunderstorm with slight hail
99 = Thunderstorm with heavy hailTips for LLMs: - Use this to explain weather conditions to users in natural language - Severity helps determine appropriate activity recommendations - Codes 0-3: Generally safe outdoor conditions - Codes 51-65: Wet conditions, bring umbrella - Codes 71-77: Snow conditions, winter gear needed - Codes 80-99: Severe weather, take precautions - Unknown codes return "Unknown weather code" - may be API error
Map icon tip:
The returned icon field is a PNG URL for the weather condition.
When building a GeoJSON FeatureCollection to show on a map, put this
URL in each feature's properties.icon field — the map renderer will
use it as the marker image instead of the default blue pin.
Example: # Get weather and interpret code forecast = await get_weather_forecast(lat, lon, current_weather=True) code = forecast.current_weather.weathercode interpretation = await interpret_weather_code(code) # Returns: WeatherCodeInterpretation(code=61, description="Slight rain", # severity="rain", icon="https://openweathermap.org/img/wn/10d@2x.png")
Inputs: weather_code (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Every tool has a clearly distinct purpose. Singular and batch variants are explicitly separated by name and description, covering different domains (geocoding, weather, air quality, marine, historical, weather codes). No overlaps or confusion.
All tools follow a consistent verb_noun pattern using snake_case. Singular tools use lowercase names (e.g., geocode_location), batch tools are prefixed with 'batch_'. The pattern is predictable and uniform across all 12 tools.
With 12 tools covering geocoding, multiple weather data types, and code interpretation with both singular and batch variants, the count is well-scoped. Each tool serves a needed function without redundancy.
The tool surface covers all major weather-related tasks: geocoding, current/forecast/historical weather, air quality, marine conditions (including tides), and weather code interpretation. Both singular and batch operations are provided, leaving no obvious gaps.
Maintenance
Related MCP Connectors
Global weather via Open-Meteo: forecast, historical, marine, air quality, geocoding, elevation.
Current weather and forecasts for any coordinates, backed b… — paid per call (x402/credits), 1 tools
Geocoding, routing, isochrones, traffic, weather, and place search for AI agents. 19 MCP tools.
Current weather and forecast lookup as an agent tool.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to access real-time and historical weather data through multiple weather APIs including OpenMeteo, Tomorrow.io, and OpenWeatherMap. Provides comprehensive meteorological information including current conditions, forecasts, historical data, and weather alerts.-
- AlicenseBqualityBmaintenanceProvides comprehensive access to Open-Meteo APIs for weather forecasts, historical data, air quality, and marine conditions. It enables LLMs to query specialized meteorological models, perform geocoding, and access advanced climate or flood projections.171,730 npm73MIT
- AlicenseAqualityDmaintenanceProvides comprehensive access to Open-Meteo weather APIs, including forecasts, historical data, air quality, marine weather, and geocoding, enabling LLMs to retrieve weather information and location data.171,730 npmMIT
- FlicenseNot gradedqualityCmaintenanceProvides real-time weather data via 12 tools (current weather, forecasts, air quality, umbrella advice, etc.) using Open-Meteo and FastMCP, enabling LLMs to answer weather-related queries.1-