OpenWeatherMap MCP Server

Overview

What it does

Access comprehensive weather data from OpenWeatherMap, the world’s leading weather data provider. Get current conditions, forecasts, air quality, alerts, and historical data for any location globally.Key Features:

Current weather conditions for any location worldwide
5-day/3-hour and hourly forecasts
Severe weather alerts and warnings
Air quality index and pollutant data
UV index and solar radiation
Historical weather data (last 5 days)
Location search and geocoding

Use Cases

Perfect for building AI-powered weather assistants and climate-aware applications.Examples:

Travel planning and weather-based recommendations
Agricultural and farming decisions
Event planning and outdoor activity scheduling
Logistics and supply chain optimization
Construction project timing
Air quality monitoring for health-conscious applications
Solar energy potential assessment
Emergency preparedness and alerts

Quick Start

Get Your API Key

1,000 API calls per day
60 calls per minute
Current weather data
5-day/3-hour forecasts
Air pollution data
UV index
Geocoding services

After signing up, find your API key in the “API keys” section of your account dashboard.

Add to NimbleBrain Studio

In NimbleBrain Studio:

Navigate to MCP Servers in the sidebar
Click Add Server
Search for “OpenWeatherMap” in the server registry
Click Configure
Paste your API key in the OPENWEATHERMAP_API_KEY field
Click Save & Enable

The server will automatically connect and become available in your AI assistant within seconds.

Test the Connection

In your Studio chat, try this prompt:

"What's the current weather in New York City?"

You should see real-time weather data including temperature, conditions, humidity, wind speed, visibility, and pressure.

Look for the 🔧 tool usage indicator in Studio to confirm the server is working correctly.

Available Tools

get_current_weather

Get current weather conditions for any location worldwide, including temperature, humidity, pressure, wind, clouds, and visibility.Parameters:

Parameter	Type	Required	Description
location	string	No*	Location name (e.g., ‘London’, ‘New York,US’, ‘Panama City, Panama’)
lat	float	No*	Latitude coordinate (use with lon)
lon	float	No*	Longitude coordinate (use with lat)
units	string	No	Units of measurement: ‘metric’ (Celsius), ‘imperial’ (Fahrenheit), ‘standard’ (Kelvin). Default: ‘metric’

*Note: Must provide either location OR coordinates (lat/lon), not both.Returns: Current weather data including:

Temperature (current, feels like, min, max)
Atmospheric pressure and humidity
Wind speed, direction, and gusts
Cloudiness and visibility
Weather conditions (rain, snow, clear, etc.)
Sunrise and sunset times
Geographic coordinates

Example Usage:

"What's the weather like in Tokyo right now?"

Example Response:

{
  "coord": {"lat": 35.6895, "lon": 139.6917},
  "weather": [{
    "main": "Clear",
    "description": "clear sky",
    "icon": "01d"
  }],
  "main": {
    "temp": 18.5,
    "feels_like": 17.8,
    "temp_min": 16.2,
    "temp_max": 20.1,
    "pressure": 1013,
    "humidity": 62
  },
  "wind": {
    "speed": 3.5,
    "deg": 180
  },
  "clouds": {"all": 0},
  "visibility": 10000,
  "dt": 1704067200,
  "sys": {
    "country": "JP",
    "sunrise": 1704063600,
    "sunset": 1704100800
  },
  "name": "Tokyo"
}

Use coordinates for precise locations. City names work well for major cities, but may be ambiguous for smaller locations.

get_forecast

Get 5-day weather forecast with 3-hour intervals (up to 40 data points). Perfect for planning activities and trips over the next several days.Parameters:

Parameter	Type	Required	Description
city	string	No*	City name (e.g., ‘London’, ‘New York,US’)
lat	float	No*	Latitude coordinate (use with lon)
lon	float	No*	Longitude coordinate (use with lat)
units	string	No	Units of measurement (‘metric’, ‘imperial’, ‘standard’). Default: ‘metric’
cnt	number	No	Number of timestamps to return (max: 40)

*Note: Must provide either city OR coordinates (lat/lon), not both.Returns: Forecast data containing:

Array of 40 forecast items (5 days × 8 three-hour intervals)
Temperature, humidity, pressure for each interval
Weather conditions and probability of precipitation
Wind speed and direction
Cloud cover and visibility
City information with timezone

Example Usage:

"What will the weather be like in Paris over the next 3 days?"

Example Response:

{
  "cod": "200",
  "cnt": 40,
  "list": [
    {
      "dt": 1704096000,
      "dt_txt": "2025-01-01 12:00:00",
      "main": {
        "temp": 8.5,
        "feels_like": 6.2,
        "temp_min": 7.1,
        "temp_max": 8.5,
        "pressure": 1015,
        "humidity": 75
      },
      "weather": [{
        "main": "Rain",
        "description": "light rain"
      }],
      "wind": {"speed": 4.2, "deg": 220},
      "pop": 0.65
    }
  ],
  "city": {
    "name": "Paris",
    "country": "FR",
    "timezone": 3600,
    "sunrise": 1704091200,
    "sunset": 1704124800
  }
}

Each forecast point represents a 3-hour window. Use the dt_txt field for human-readable timestamps.

get_hourly_forecast

Get detailed hourly weather forecast for the next 48 hours (requires coordinates). More precise than the 3-hour forecast for short-term planning.Parameters:

Parameter	Type	Required	Description
lat	float	Yes	Latitude coordinate
lon	float	Yes	Longitude coordinate
units	string	No	Units of measurement (‘metric’, ‘imperial’, ‘standard’). Default: ‘metric’
cnt	number	No	Number of hours to return (max: 96)

Returns: Hourly forecast data for next 48 hours including:

Temperature and feels-like for each hour
Weather conditions and precipitation probability
Wind speed, direction, and gusts
Cloud cover and visibility
Atmospheric pressure and humidity

Example Usage:

"Give me the hourly forecast for San Francisco (37.7749, -122.4194) for the next 24 hours"

Use search_city tool first if you don’t have coordinates. This tool provides more detailed short-term predictions than the 3-hour forecast.

get_weather_alerts

Get severe weather alerts and warnings for a location. Critical for safety and emergency preparedness planning.Parameters:

Parameter	Type	Required	Description
lat	float	Yes	Latitude coordinate
lon	float	Yes	Longitude coordinate

Returns: Alert data containing:

alerts - Array of active weather alerts
sender_name - Alert issuing authority
event - Type of weather event
start - Alert start time (Unix timestamp)
end - Alert end time (Unix timestamp)
description - Detailed alert description
timezone - Location timezone

Example Usage:

"Are there any severe weather warnings for Miami, Florida right now?"

Example Response:

{
  "lat": 25.7617,
  "lon": -80.1918,
  "timezone": "America/New_York",
  "alerts": [
    {
      "sender_name": "NWS Miami FL",
      "event": "Hurricane Warning",
      "start": 1704067200,
      "end": 1704153600,
      "description": "Hurricane Warning in effect. Winds of 74 mph or higher expected. Preparations to protect life and property should be rushed to completion."
    }
  ]
}

Always check for alerts before outdoor activities in unfamiliar areas. Empty alerts array means no active warnings.

get_air_quality

Get air quality index (AQI) and detailed pollutant concentrations. Essential for health-conscious applications and environmental monitoring.Parameters:

Parameter	Type	Required	Description
lat	float	Yes	Latitude coordinate
lon	float	Yes	Longitude coordinate

Returns: Air quality data containing:

aqi - Air Quality Index (1=Good, 2=Fair, 3=Moderate, 4=Poor, 5=Very Poor)
co - Carbon monoxide (μg/m³)
no - Nitrogen monoxide (μg/m³)
no2 - Nitrogen dioxide (μg/m³)
o3 - Ozone (μg/m³)
so2 - Sulphur dioxide (μg/m³)
pm2_5 - Fine particles matter (μg/m³)
pm10 - Coarse particles matter (μg/m³)
nh3 - Ammonia (μg/m³)

Example Usage:

"What's the air quality in Beijing? Is it safe to exercise outdoors?"

Example Response:

{
  "coord": {"lat": 39.9042, "lon": 116.4074},
  "list": [
    {
      "main": {"aqi": 4},
      "components": {
        "co": 500.5,
        "no": 0.1,
        "no2": 42.3,
        "o3": 15.2,
        "so2": 8.5,
        "pm2_5": 65.2,
        "pm10": 85.3,
        "nh3": 2.1
      },
      "dt": 1704067200
    }
  ]
}

AQI levels: 1 (Good) - safe for everyone, 2 (Fair) - acceptable, 3 (Moderate) - sensitive groups may be affected, 4 (Poor) - everyone may be affected, 5 (Very Poor) - health alert.

get_weather_by_zip

Get current weather using ZIP or postal code. Convenient for applications that collect user ZIP codes.Parameters:

Parameter	Type	Required	Description
zip_code	string	Yes	ZIP or postal code
country_code	string	No	2-letter country code (e.g., ‘US’, ‘GB’, ‘CA’, ‘DE’)
units	string	No	Units of measurement (‘metric’, ‘imperial’, ‘standard’). Default: ‘metric’

Returns: Same weather data as get_current_weather, including temperature, conditions, wind, humidity, and pressure.Example Usage:

"What's the weather for ZIP code 90210?"

Example Response:

{
  "coord": {"lat": 34.0901, "lon": -118.4065},
  "weather": [{"main": "Clear", "description": "clear sky"}],
  "main": {
    "temp": 22.5,
    "feels_like": 21.8,
    "humidity": 45,
    "pressure": 1015
  },
  "wind": {"speed": 2.5},
  "name": "Beverly Hills"
}

Including the country code (e.g., “90210,US”) ensures accurate results, especially for postal codes that exist in multiple countries.

search_city

Search for cities by name and get their coordinates. Essential for converting user-friendly location names to coordinates for other tools.Parameters:

Parameter	Type	Required	Description
city_name	string	Yes	City name to search for
limit	number	No	Number of results to return (max: 5). Default: 5

Returns: Array of matching cities with:

name - City name
lat - Latitude
lon - Longitude
country - Country code
state - State/region name (if available)
local_names - Names in different languages

Example Usage:

"Find the coordinates for Springfield"

Example Response:

{
  "results": [
    {
      "name": "Springfield",
      "lat": 42.1015,
      "lon": -72.5898,
      "country": "US",
      "state": "Massachusetts"
    },
    {
      "name": "Springfield",
      "lat": 39.7817,
      "lon": -89.6501,
      "country": "US",
      "state": "Illinois"
    },
    {
      "name": "Springfield",
      "lat": 37.2153,
      "lon": -93.2982,
      "country": "US",
      "state": "Missouri"
    }
  ]
}

Many city names exist in multiple locations. Always present options to users when multiple matches are found.

get_historical_weather

Get historical weather data for a specific date within the last 5 days. Useful for analysis, reporting, and comparisons.Parameters:

Parameter	Type	Required	Description
lat	float	Yes	Latitude coordinate
lon	float	Yes	Longitude coordinate
dt	number	Yes	Unix timestamp (UTC) for the historical date
units	string	No	Units of measurement (‘metric’, ‘imperial’, ‘standard’). Default: ‘metric’

Returns: Historical weather data for the specified date including:

Temperature and atmospheric conditions
Weather descriptions
Wind speed and direction
Cloud cover and humidity
Sunrise and sunset times

Example Usage:

"What was the weather in Seattle 3 days ago?"

Historical data is only available for the last 5 days. For older data, a paid OpenWeatherMap plan is required.

get_uv_index

Get UV index for a location. Critical for outdoor safety and health recommendations.Parameters:

Parameter	Type	Required	Description
lat	float	Yes	Latitude coordinate
lon	float	Yes	Longitude coordinate

Returns: UV index data including:

value - UV index value
date - Unix timestamp
date_iso - ISO format date
lat - Latitude
lon - Longitude

UV Index Scale:

0-2: Low (minimal protection needed)
3-5: Moderate (protection recommended)
6-7: High (protection essential)
8-10: Very High (extra protection required)
11+: Extreme (avoid sun exposure)

Example Usage:

"What's the UV index in Sydney today? Should I wear sunscreen?"

Example Response:

{
  "lat": -33.8688,
  "lon": 151.2093,
  "date_iso": "2025-01-15T12:00:00Z",
  "date": 1704067200,
  "value": 8.5
}

UV index peaks between 10 AM and 4 PM. Always recommend sunscreen for UV index of 3 or higher.

get_weather_map

Get weather map layer tile data for visualizations. Advanced feature for building custom weather map interfaces.Parameters:

Parameter	Type	Required	Description
layer	string	Yes	Map layer type: ‘temp_new’, ‘precipitation_new’, ‘clouds_new’, ‘pressure_new’, ‘wind_new’
z	number	Yes	Zoom level (0-15)
x	number	Yes	Tile X coordinate
y	number	Yes	Tile Y coordinate

Returns: Map tile information including:

tile_url - URL to fetch the weather map tile image
layer - Layer type
zoom - Zoom level
x, y - Tile coordinates

Example Usage:

"Get temperature map tile for zoom 5, coordinates 10,5"

Example Response:

{
  "layer": "temp_new",
  "zoom": 5,
  "x": 10,
  "y": 5,
  "tile_url": "https://tile.openweathermap.org/map/temp_new/5/10/5.png?appid=...",
  "info": "Use this URL to fetch the weather map tile image"
}

This is an advanced tool for developers building custom weather map visualizations. Most applications won’t need this feature.

Authentication

API Key Required: This server requires an OpenWeatherMap API key to function.

Getting Your API Key

Create a free account at openweathermap.org/users/sign_up
Verify your email address
Navigate to your account dashboard
Go to the “API keys” section
Copy your default API key (or create a new one)
Add it to your Studio server configuration

Rate Limits

Plan	Calls/Day	Calls/Minute	Price
Free	1,000	60	$0
Startup	100,000	600	$40/month
Developer	1,000,000	600	$125/month
Professional	3,000,000	600	$500/month
Enterprise	Custom	Custom	Contact sales

If you exceed rate limits, requests will fail with a 429 error. Monitor your usage in Studio’s server settings and consider upgrading your OpenWeatherMap plan for production use.

Managing Your API Key in Studio

Your API key is securely stored in NimbleBrain Studio. To update it:

Go to Settings → MCP Servers
Find “OpenWeatherMap” in your server list
Click Edit Configuration
Update your API key in the OPENWEATHERMAP_API_KEY field
Click Save

Studio automatically manages server connections - no manual restarts required. Changes take effect immediately.

Example Workflows

Current Weather Check
Travel Planning
Air Quality Monitoring
Event Planning
UV & Sun Safety
Multi-Location Analysis
Severe Weather Alerts
ZIP Code Lookup

Scenario: Quick weather check before commuting or meetingsPrompt:

"What's the weather like in London right now?"

What happens:

Gets current temperature and conditions
Shows humidity and wind speed
Indicates precipitation and visibility
Reports cloud cover and pressure

Time: ~1 second API calls: 1

You can check multiple cities at once in Studio: “Compare weather in Paris, Tokyo, and New York”

All examples work in NimbleBrain Studio’s natural language interface - no code or configuration required!

Troubleshooting

Rate Limit Exceeded

Error Message:

429 Too Many Requests - API rate limit exceeded

Cause: You’ve exceeded your daily (1,000 calls) or per-minute (60 calls) API limit on the free tierSolutions:

Wait until your limit resets (daily limits reset at midnight UTC, per-minute limits reset after 60 seconds)
Check your usage in the OpenWeatherMap dashboard
Upgrade to a paid plan for higher limits (100K-3M calls/day)
Space out your requests over time in Studio conversations
Reduce the number of locations you’re tracking simultaneously

To check your usage:

Go to Studio Settings → MCP Servers
Click on OpenWeatherMap
View API usage metrics

Studio shows real-time API usage. Consider upgrading your OpenWeatherMap plan if you frequently hit limits during normal use.

Invalid API Key

Error Message:

401 Unauthorized - Invalid API key

Cause: API key is missing, incorrect, expired, or revokedSolutions:

Verify your API key in Studio server settings (no extra spaces)
Check your OpenWeatherMap account is active and email verified
Regenerate your API key from the OpenWeatherMap dashboard
Ensure your API key hasn’t been revoked (check account notifications)

To update in Studio:

Settings → MCP Servers → OpenWeatherMap
Click Edit Configuration
Paste new API key in OPENWEATHERMAP_API_KEY field
Click Save
Test with: “What’s the weather in London?”

Common Mistakes:

Extra spaces before/after the API key when pasting
Copying only part of the API key from the dashboard
Using an API key from a different weather service

Studio validates your API key automatically when you save. You’ll see a success message if it’s correct.

Location Not Found

Error Message:

404 Not Found - City not found

Cause: Invalid or ambiguous location name, or location doesn’t exist in OpenWeatherMap’s databaseSolutions:

Use more specific location names (e.g., “London, UK” instead of just “London”)
Check spelling of city name
Use major cities or well-known locations (small towns may not be in database)
Add country code to disambiguate (e.g., “Paris, FR” vs “Paris, TX, US”)
For small towns, try using the nearest major city

Examples in Studio:

❌ "What's the weather in Springfield?" → Too ambiguous
✅ "What's the weather in Springfield, Illinois?" → Much better
✅ "What's the weather in London, UK?" → Clear and specific

Studio’s AI can help disambiguate locations if you provide context in your conversation. For example: “I’m planning a trip to Paris, France next month.”

Coordinates Out of Range

Error Message:

400 Bad Request - Invalid coordinates

Cause: Latitude or longitude values are outside valid rangesSolutions:

Verify latitude is between -90 and 90
Verify longitude is between -180 and 180
Check for swapped lat/lon values (common mistake)
Ensure coordinates are decimal degrees, not degrees-minutes-seconds
Remove any degree symbols or directional letters (N, S, E, W)

Valid Coordinate Examples:

New York: lat=40.7128, lon=-74.0060
Sydney: lat=-33.8688, lon=151.2093
London: lat=51.5074, lon=-0.1278

Server Not Responding

Error Message:

Server connection timeout

Server not responding

Cause: Studio cannot connect to the OpenWeatherMap MCP serverSolutions:

Check your internet connection
Verify the server is enabled in Studio (Settings → MCP Servers)
Try disabling and re-enabling the server in Studio
Check Studio status page for any service interruptions
Refresh your Studio browser tab

Quick Fix in Studio:

Go to Settings → MCP Servers
Find OpenWeatherMap in the list
Toggle it Off, wait 5 seconds
Toggle it On again
Try your query again

Studio manages all server infrastructure automatically - there’s no local setup or Docker containers to troubleshoot.

Data Not Available

Error Message:

Data not available for this location

or certain fields return nullCause: Some features require paid plans or aren’t available for all locationsPossible Reasons:

Severe weather alerts only available where local weather services provide them
Historical data beyond 5 days requires a paid plan
Minute-by-minute precipitation data (paid feature)
Some small towns have limited data coverage
UV index may not be available for all coordinates

Solutions:

Try nearby major cities for better data coverage
Check OpenWeatherMap’s data coverage map for your region
Verify the feature is included in your plan tier (check documentation)
Upgrade to a paid plan for extended features (historical data, minute forecasts)
Use alternative tools when specific data is unavailable (e.g., forecast instead of alerts)

Slow Response Times

Symptoms:

Requests taking longer than 3-5 seconds
Timeouts when fetching weather data
Intermittent slow responses

Cause: Network latency, OpenWeatherMap API delays, or server loadSolutions:

Check your internet connection speed and stability
Verify OpenWeatherMap API status at status.openweathermap.org
Try again in a few moments (may be temporary API congestion)
Use smaller forecast ranges (cnt parameter) for faster responses
Implement timeout handling in your application (recommend 10s timeout)
Consider caching responses locally for frequently requested locations

Expected Response Times:

Current weather: 0.5-1 second
5-day forecast: 1-2 seconds
Air quality: 1-2 seconds
Search city: 1-2 seconds
Weather alerts: 2-3 seconds (uses One Call API)
Multiple queries: 2-5 seconds

Historical Data Limitations

Error Message:

Historical data not available or requires paid plan

Cause: Attempting to access historical data beyond the free tier’s 5-day limitFree Tier Limitations:

Only last 5 days of historical data
Hourly data availability varies by location
No historical forecasts (only actual conditions)

Solutions:

For dates within last 5 days: Use get_historical_weather with proper Unix timestamp
For older data: Upgrade to a paid OpenWeatherMap plan
For climate averages: Consider using monthly climate normals (separate API)
Store your own historical data by polling current conditions regularly

Converting Dates to Unix Timestamps:

Use online converters or programming languages
Example: January 10, 2025 12:00 UTC = 1704891600
Ensure timestamp is in UTC, not local time

Links & Resources

GitHub Repository

View source code, report issues, and contribute to the project

OpenWeatherMap API Docs

Official OpenWeatherMap API reference, data coverage, and features

Docker Image

Pull the latest container image from GitHub Container Registry

Report Issues

Found a bug or have a feature request? Submit an issue on GitHub

National Parks

Plan outdoor activities with park information and visitor data

Google Maps

Get directions and travel time estimates affected by weather

Cal.com

Schedule events and meetings based on weather conditions

Need help? Join the NimbleBrain Discord or email [email protected]

Get Started

Core Features

Developer Tools

Overview

What it does

Use Cases

Quick Start

Available Tools

Authentication

Getting Your API Key

Rate Limits

Managing Your API Key in Studio

Example Workflows

Troubleshooting

Links & Resources

GitHub Repository

OpenWeatherMap API Docs

Docker Image

Report Issues

National Parks

Google Maps

Cal.com

Get Started

Core Features

Developer Tools

​Overview

What it does

Use Cases

​Quick Start

​Available Tools

​Authentication

​Getting Your API Key

​Rate Limits

​Managing Your API Key in Studio

​Example Workflows

​Troubleshooting

​Links & Resources

GitHub Repository

OpenWeatherMap API Docs

Docker Image

Report Issues

​Related MCP Servers

National Parks

Google Maps

Cal.com

Overview

Quick Start

Available Tools

Authentication

Getting Your API Key

Rate Limits

Managing Your API Key in Studio

Example Workflows

Troubleshooting

Links & Resources

Related MCP Servers