KN
Data Analytics

KnowAir Weather MCP Server — Real-Time Air Quality Forecasts

Access real-time weather and air quality forecasts with the KnowAir MCP server — PM2.5/PM10, O₃, AQI (CN/US), 72-hour/7-day forecasts, alerts and astronomy.

View on GitHub
Quick Install
npx -y @shuowang-ai/Weather-MCP

Overview

KnowAir Weather MCP Server provides a machine-friendly API for real-time weather and air quality forecasts. Implemented as an MCP (Model Context Protocol) server, it exposes air quality and meteorological model outputs—PM2.5, PM10, O₃, AQI (China/US), short (72-hour) and extended (7-day) forecasts—along with alerts and simple astronomy data (sunrise/sunset). The server is intended to be used as a tool component in agent or LLM workflows, microservices, dashboards, or IoT pipelines that need programmatic access to up-to-date environmental information.

Because the server is packaged as an MCP-compatible service, it can be integrated into multi-tool AI systems or called directly from client applications. Developers can deploy it as a standalone web service (Docker or local Python runtime), configure data sources and model parameters, and query the server for location-based forecasts and advisory alerts.

Features

  • Real-time air quality metrics: PM2.5, PM10, O₃
  • Dual AQI scales: CN (China) and US
  • 72-hour (hourly) and 7-day (daily) forecasts
  • Health and advisory alerts when thresholds are exceeded
  • Astronomy data: sunrise, sunset, solar times useful for exposure modeling
  • MCP-compatible API for model/tool orchestration
  • Lightweight deployment options (local runtime or container)

Installation / Configuration

Clone the repository and choose a deployment path (Docker recommended for quick start).

Clone the repo:

git clone https://github.com/shuowang-ai/Weather-MCP.git
cd Weather-MCP

Option A — Run with Docker (recommended):

# build image
docker build -t knowair-weather-mcp .

# run container (example exposing port 8000)
docker run -d -p 8000:8000 \
  -e API_KEY="your_data_source_key" \
  -e DEFAULT_LOCATION="37.7749,-122.4194" \
  --name knowair-mcp knowair-weather-mcp

Option B — Run locally with Python:

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# set environment variables
export API_KEY="your_data_source_key"
export HOST="0.0.0.0"
export PORT="8000"

# start server (example using uvicorn/FastAPI)
uvicorn app.main:app --host $HOST --port $PORT

Configuration file (example YAML):

data_sources:
  open_meteo:
    api_key: YOUR_OPEN_METEO_KEY
default:
  location: [37.7749, -122.4194]
thresholds:
  pm25_warning: 35
  aqi_us_warning: 101

Adjust environment variables and config file to point to your preferred data providers and to set alert thresholds.

Available Resources

The server exposes REST endpoints suitable for MCP/tool use and direct queries. Typical endpoints include:

  • GET /forecast?lat={lat}&lon={lon}&hours=72
  • GET /air-quality?lat={lat}&lon={lon}
  • GET /aqi?lat={lat}&lon={lon}&scale=US|CN
  • GET /alerts?lat={lat}&lon={lon}
  • GET /astronomy?lat={lat}&lon={lon}&date=YYYY-MM-DD
  • POST /mcp/invoke — MCP-compatible tool invocation (context + params)

Example curl: fetch 72-hour forecast

curl "http://localhost:8000/forecast?lat=37.7749&lon=-122.4194&hours=72"

Common response fields (JSON):

FieldTypeDescription
pm25numberCurrent PM2.5 concentration (µg/m³)
pm10numberCurrent PM10 concentration (µg/m³)
o3numberCurrent Ozone concentration (ppb or µg/m³)
aqi_usintegerAQI using US EPA breakpoints
aqi_cnintegerAQI using China standard
forecast_72harrayHourly forecast objects for next 72 hours
forecast_7darrayDaily forecast objects for next 7 days
alertsarrayActive advisories or warnings
astronomyobjectsunrise, sunset, solarNoon, etc.

Use Cases

  • Dashboard integration: feed the 72-hour PM2.5 and AQI series into a web dashboard with color coding and thresholds to inform users of short-term exposure risk.

    • Query /forecast hourly and plot pm25 over time, trigger UI banner if aqi_us > 100.

  • Alerting and automation: connect the alerts endpoint to a notification system to send SMS/email when pollutants exceed configured thresholds.

    • Poll /alerts every 15 minutes; if alerts array non-empty, send notification.

  • LLM tool integration (MCP): register the Weather MCP server as a tool in an agent to provide context-aware advice, e.g., “Should I schedule outdoor running tomorrow?”

    • Agent calls POST /mcp/invoke with location & time context; server returns forecast + recommendation.

  • Research and analytics: bulk-download 7-day forecasts across grid points to analyze exposure patterns or validate air quality models.

    • Use scripted calls to /forecast with different lat/lon pairs and aggregate results.

  • IoT & edge devices: expose a compact API to smart home hubs, allowing HVAC systems to adjust filtration based on incoming PM2.5 forecasts.

Tips for Developers

  • Cache forecasts for short durations to reduce upstream API usage (e.g., cache hourly results for 10–15 minutes).
  • Normalize units in your client: some data sources use different units for ozone and particulate matter.
  • Tune thresholds per region: AQI interpretation and health advice vary; expose configurable threshold values in your deployment.
  • Secure API keys and restrict host/network access when deploying in production.

Repository and source code: https://github.com/shuowang-ai/Weather-MCP

Tags:data-analytics