Weather MCP Server with WeatherAPI Integration

Overview

This MCP (Model Context Protocol) server provides real-time weather information by integrating with WeatherAPI (weatherapi.com). It implements a simple tool server that exposes weather-oriented endpoints and an MCP-compatible interface so language models or agents can call weather tools programmatically. The server fetches current conditions, multi-day forecasts, and active alerts for any queried location and returns structured JSON responses suitable for downstream processing.

The project is useful for developers building conversational assistants, automation pipelines, or agent-based applications that need timely weather data. By running the MCP server locally or in your cloud environment, you can keep your WeatherAPI key and business logic centralized while enabling LLMs to call weather tools through a predictable protocol.

Features

• Fetch current weather conditions (temperature, humidity, wind, condition text, icon)
• Multi-day forecasts (1–10 days, configurable)
• Active severe weather alerts (where available)
• Geocoding support (query by city name, postal code, or lat/lon)
• MCP-compatible tool manifest for LLMs and agents
• Lightweight Node.js implementation with Docker support
• Rate-limit aware and simple error handling with informative responses

Installation / Configuration

Prerequisites: Node.js 18+ and a WeatherAPI key (register at https://www.weatherapi.com/).

1. Clone the repo and install dependencies:

git clone https://github.com/devilcoder01/weather-mcp-server.git
cd weather-mcp-server
npm install

2. Create a .env file in the project root with your WeatherAPI key and configuration:

WEATHERAPI_KEY=your_weatherapi_key_here
PORT=3000
DEFAULT_UNITS=metric   # or 'imperial'
DEFAULT_FORECAST_DAYS=3

3. Start the server:

npm start
# or for development
npm run dev

4. Docker (optional):

docker build -t weather-mcp-server .
docker run -e WEATHERAPI_KEY=your_key -p 3000:3000 weather-mcp-server

Available Tools / Available Resources

The server exposes a set of HTTP endpoints that correspond to tools an LLM or agent can call. Below is a summary table:

Example: MCP-style tool call (JSON POST to an MCP agent endpoint, if integrating directly):

{
  "tool": "weather-current",
  "args": {
    "location": "San Francisco, CA",
    "units": "metric"
  }
}

Example curl requests:

# Current weather
curl "http://localhost:3000/weather/current?q=London&units=metric"

# Forecast (3 days)
curl "http://localhost:3000/weather/forecast?q=94016&days=3"

API Response Examples

Current weather (abbreviated):

{
  "location": {"name": "London", "region": "City of London", "country": "UK"},
  "current": {
    "temp_c": 14.3,
    "condition": {"text": "Partly cloudy", "icon": "//cdn.weatherapi.com/..."},
    "wind_kph": 13.0,
    "humidity": 72
  }
}

Forecast (abbreviated):

{
  "location": { "name": "94016", "country": "USA" },
  "forecast": {
    "forecastday": [
      { "date": "2026-04-10", "day": {"maxtemp_c": 18.5, "mintemp_c": 9.0, "condition": {"text": "Sunny"}} },
      ...
    ]
  }
}

Use Cases

• Conversational assistants: Allow an LLM-based assistant to answer user weather queries by calling the MCP tool for current conditions or forecasts.
  • Example: “What’s the weather in Paris this weekend?” → Agent calls /weather/forecast?q=Paris&days=3 and returns summary to user.
• Automation pipelines: Periodically query alerts for a set of locations and trigger notifications or workflows when severe weather is detected.
  • Example cron job queries /weather/alerts and posts results to a Slack webhook when alert list is non-empty.
• Context enrichment: Add precise weather context to downstream tasks (e.g., delivery ETAs, outdoor event planning).
  • Example: A delivery ETA microservice queries /weather/current for route endpoints to adjust time estimates.

Notes & Best Practices

• Rate limits: WeatherAPI free/tiered plans have request limits. Cache responses when appropriate and respect usage quotas.
• Units & localization: Use the units parameter (metric/imperial) to match consumer expectations. The server returns raw structured fields to allow custom formatting.
• Security: Keep WEATHERAPI_KEY secret (use environment variables, secret managers, or container secrets). If exposing the server publicly, enable TLS and authentication.
• Extensibility: The codebase is designed so you can add additional tools (e.g., historical weather, UV index) and update the MCP manifest to expose them to agents.

For implementation details and source code, see the project repository on GitHub: https://github.com/devilcoder01/weather-mcp-server