OP
Location

OpenWeather MCP Server: Current and Forecast Weather

Get current and forecast weather for any location using the OpenWeather MCP server via the free OpenWeatherMap API.

View on GitHub
Quick Install
npx -y @mschneider82/mcp-openweather

Overview

The OpenWeather MCP Server provides a simple Model Context Protocol (MCP)–compatible wrapper around the free OpenWeatherMap APIs. It lets LLMs and other MCP-aware clients retrieve current weather and multi-day forecasts for any location (by city name or geographic coordinates) while centralizing configuration such as API keys, default units, and rate limiting.

This server is useful when you want to expose weather lookup capabilities to an LLM or integrate weather data into an agent workflow without embedding your OpenWeatherMap API key into multiple clients. The MCP abstraction provides typed tool descriptions and a predictable JSON interface that an LLM can call directly to fetch live weather information.

Features

  • Current weather lookup (temperature, humidity, description, wind, etc.)
  • Forecast retrieval (hourly / multi-day forecast summary)
  • Location by city name, city ID, or latitude/longitude
  • Unit options (metric, imperial, standard)
  • Simple environment-based configuration (API key and defaults)
  • Deployable locally or in containers
  • MCP-compatible tool manifest so LLMs can discover and call the weather tools

Installation / Configuration

Clone the repository and run locally (Node.js is assumed). Adjust commands to match the runtime in the repository if different.

  1. Clone the repo:
git clone https://github.com/mschneider82/mcp-openweather.git
cd mcp-openweather
  1. Install dependencies and run:
# If this project uses npm
npm install
npm start

# Or, if it uses yarn
yarn install
yarn start
  1. Set required environment variables (example .env):
OPENWEATHER_API_KEY=your_openweathermap_api_key
PORT=8080
DEFAULT_UNITS=metric   # metric | imperial | standard

Docker (example):

docker run -e OPENWEATHER_API_KEY=your_api_key -e PORT=8080 -p 8080:8080 mcp-openweather:latest

Note: The server requires an OpenWeatherMap API key. You can sign up for a free key at https://openweathermap.org/.

Available Resources

  • GitHub repository: https://github.com/mschneider82/mcp-openweather
  • OpenWeatherMap API docs: https://openweathermap.org/api
  • MCP (Model Context Protocol) reference: consult your MCP integrator or the MCP spec used in your agent framework

The server exposes MCP tools (tool manifest) that describe available operations so an LLM can discover them programmatically. Typical tool names you will see in the manifest:

  • current_weather — returns present conditions for a location
  • forecast — returns a forecast (daily or hourly depending on OpenWeather endpoint used)

API / Tool Usage Examples

Below are concrete examples showing how a client or an LLM might call the server tools. Adjust endpoints and payloads to match the actual MCP route your server publishes (the examples use /call as a generic invocation endpoint).

Example: Get current weather by city name

curl -X POST http://localhost:8080/call \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "current_weather",
    "args": {
      "location": "Austin,TX,US",
      "units": "metric"
    }
  }'

Sample JSON response (abbreviated):

{
  "location": "Austin,TX,US",
  "timestamp": 1680000000,
  "temperature": 24.3,
  "feels_like": 25.0,
  "humidity": 63,
  "wind_speed": 4.2,
  "weather": "light rain",
  "source": "openweathermap"
}

Example: Get 5-day forecast by coordinates

curl -X POST http://localhost:8080/call \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "forecast",
    "args": {
      "lat": 30.2672,
      "lon": -97.7431,
      "units": "imperial",
      "days": 5
    }
  }'

Forecast response: typically returns an array of entries (timestamped, temperature ranges, precipitation chance, summary).

Use Cases

  • LLM assistants: Provide the assistant with a tool it can call to answer queries like “What’s the current weather in Paris?” without revealing your API key to the model.
  • Chatbots and agents: Enrich conversational agents with live weather context to make recommendations (e.g., suggest packing an umbrella).
  • Automation & triggers: Use the server in scheduled jobs or workflows to pull forecast data and trigger alerts (heat warnings, precipitation forecasts).
  • Dashboard backends: Centralize weather calls from multiple frontend clients, apply caching or rate-limiting, and keep API keys secure on the server.

Parameters & Notes

  • Location input: the server accepts city names (optionally with country), city IDs, or coordinates (lat/lon). Use whichever is most reliable for your application.
  • Units: metric (Celsius), imperial (Fahrenheit), or standard (Kelvin). Set DEFAULT_UNITS to control defaults.
  • API key limits: free OpenWeatherMap plans have rate limits — consider caching responses for frequent queries.
  • Error handling: the server forwards OpenWeatherMap errors (quota exceeded, invalid API key). Make sure your client handles 4xx/5xx responses.

For quick questions or to contribute, open an issue or pull request on the GitHub repo: https://github.com/mschneider82/mcp

Tags:location