OpenWeatherMap MCP Server

A Model Context Protocol (MCP) server that provides comprehensive weather data and forecasts through the OpenWeatherMap API. This server enables AI assistants to access real-time weather information, forecasts, air quality data, and location services.

Features

Weather Tools

• Current Weather - Get current conditions for any location
• Weather Forecast - 5-day weather forecast with 3-hour intervals
• Hourly Forecast - Detailed hourly forecasts for up to 48 hours
• Daily Forecast - Daily weather forecasts for up to 8 days with temperature ranges and astronomical data
• Minutely Forecast - Minute-by-minute precipitation forecasts for the next hour
• Weather Alerts - Active weather warnings and alerts with severity classification

Air Quality & Location

• Current Air Pollution - Real-time air quality index and pollutant measurements
• Location Info - Reverse geocoding to get location details from coordinates
• OneCall Weather - Comprehensive weather data combining multiple forecasts
• Air Pollution - Historical and forecast air quality data
• Geocoding - Convert location names to coordinates

Installation

Prerequisites

• Bun runtime
• OpenWeatherMap API key (free at openweathermap.org)

Setup

1. Clone the repository:

git clone https://github.com/robertn702/mcp-openweathermap.git
cd mcp-openweathermap

2. Install dependencies:

bun install

3. Set up your environment variables:

cp .env.example .env
# Edit .env and add your OpenWeatherMap API key

Environment variables:

• `OPENWEATHER_API_KEY` - Your OpenWeatherMap API key (required for stdio transport only)
• `PORT` - Server port for HTTP transport (default: 3000)
• `MCP_TRANSPORT` - Transport type: `stdio` or `httpStream` (default: stdio)
• `MCP_ENDPOINT` - HTTP endpoint path (default: /stream)

Usage

Running the Server

Stdio Transport (default):

bun run src/main.ts

HTTP Stream Transport:

MCP_TRANSPORT=httpStream PORT=3000 bun run src/main.ts

Claude Desktop Configuration

Add this configuration to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "openweathermap": {
      "command": "npx",
      "args": ["mcp-openweathermap"],
      "env": {
        "OPENWEATHER_API_KEY": "your-api-key-here"
      }
    }
  }
}

API Tools

Weather Information

• `get-current-weather` - Current weather conditions
• `get-weather-forecast` - 5-day forecast
• `get-hourly-forecast` - Hourly forecasts (up to 48 hours)
• `get-daily-forecast` - Daily forecasts (up to 8 days)
• `get-minutely-forecast` - Minute-by-minute precipitation

Alerts & Air Quality

• `get-weather-alerts` - Weather warnings and alerts
• `get-current-air-pollution` - Current air quality data
• `get-air-pollution` - Air quality forecasts and history

Location Services

• `get-location-info` - Reverse geocoding from coordinates
• `geocode-location` - Convert addresses to coordinates
• `get-onecall-weather` - Comprehensive weather data

Development

Running in Development

bun run src/main.ts

Testing with MCP Inspector

bun run src/main.ts

Then connect the MCP Inspector to test the tools interactively.

Build

bun run build

Authentication

Stdio Transport: Requires `OPENWEATHER_API_KEY` environment variable.

HTTP Transport: The OpenWeatherMap API key is passed as a bearer token in the HTTP request headers. No environment variable needed.

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• OpenWeatherMap API Documentation
• openweather-api-node Library - The underlying API client
• Model Context Protocol Documentation
• Issue Tracker