Weather MCP Service

A lite weather service providing live weather data and forecasts via both REST API and MCP (Model Context Protocol) endpoints.

A minimal, production-ready weather service designed for local deployment with dual protocol support and comprehensive monitoring.

TypeScript Node.js Docker

Quick Start

# Clone & install git clone <repo-url> cd weather-mcp-db npm install # Set up environment cp .env.example .env # Add your WeatherAPI.com key to .env # Get your free API key at: https://www.weatherapi.com/ # Run npm run dev

Server runs on: http://localhost:3000

Weather Data Source

This service uses WeatherAPI.com for weather data, which provides:

Real-time weather data for any location worldwide
14-day weather forecasts with hourly and daily intervals
Historical weather data going back to 2010
Air quality data and weather alerts
Free tier with 1 million calls per month
Reliable uptime and fast response times

Getting Your API Key

Visit WeatherAPI.com
Click "Get Started" or "Sign Up"
Create a free account (no credit card required)
Copy your API key from the dashboard
Add it to your .env file: WEATHER_API_KEY=your_key_here

📖 Documentation: WeatherAPI.com Docs

API

REST Endpoints

GET /api/weather?city=London # Current weather GET /api/forecast?city=London # 3-day forecast GET /api/local # Default location GET /api/health # Health check

Supported Query Formats:

City names: London, New York, Tokyo
Coordinates: 48.8567,2.3508 (lat,lon)
US ZIP codes: 10001, 90210
UK postcodes: SW1, M1 1AA
Airport codes: LHR, JFK (via IATA)
IP addresses: auto:ip for IP lookup

MCP Protocol

POST /mcp # MCP JSON-RPC 2.0

Available Tools:

get_weather - Current weather for a city
get_forecast - Weather forecast (1-10 days)
get_local_weather - Default location weather

Usage

REST API

# Current weather curl "http://localhost:3000/api/weather?city=London" # Forecast (1-14 days) curl "http://localhost:3000/api/forecast?city=London&days=5" # Default location weather curl "http://localhost:3000/api/local" # Health check curl "http://localhost:3000/api/health"

MCP Protocol

# List tools curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' # Get weather curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_weather","arguments":{"city":"London"}}}'

Development

npm run dev # Development server npm run build # Build for production npm run mcp # Standalone MCP server (stdio) npm test # Run tests npm run lint # Lint code

Deployment

Docker

# Local development docker-compose up -d # Production docker build -t weather-mcp-db . docker run -p 3000:3000 -e WEATHER_API_KEY=your_key weather-mcp-db

Kubernetes

# Using Helm helm install weather-service ./helm/weather-service \ --set env.WEATHER_API_KEY=your_key

Configuration

Variable	Default	Description
`WEATHER_API_KEY`	-	WeatherAPI.com key (required)
`DEFAULT_LOCATION`	London	Default city
`TEMP_UNIT`	C	Temperature unit
`PORT`	3000	Server port

Architecture

┌─────────────┐ ┌─────────────┐ │ REST Client │ │ MCP Client │ └──────┬──────┘ └──────┬──────┘ │ │ └──────────┬───────┘ │ ┌────────▼────────┐ │ Express Server │ │ /api + /mcp │ └────────┬────────┘ │ ┌────────▼────────┐ │ Weather Service │ │ WeatherAPI.com │ └─────────────────┘

Features

✅ Dual Protocol - REST + MCP in one server
✅ Official MCP SDK - @modelcontextprotocol/sdk
✅ TypeScript - Full type safety
✅ Security - Rate limiting, validation, headers
✅ Monitoring - Health checks, metrics, logging
✅ Testing - 68 tests (unit, integration, e2e)
✅ Docker - Multi-stage build with nginx
✅ Kubernetes - Helm charts included

License

MIT

Weather MCP Service

Weather MCP Service

Quick Start

Weather Data Source

Getting Your API Key

API

REST Endpoints

MCP Protocol

Usage

REST API

MCP Protocol

Development

Deployment

Docker

Kubernetes

Configuration

Architecture

Features

License

New MCP Servers

MCP directory API