🇮🇳 Indian Weather MCP Server

A comprehensive Model Context Protocol (MCP) server providing detailed weather information, air quality data, and agricultural insights for Indian cities. Built with TypeScript and powered by Open-Meteo APIs.

✨ Features

🌤️ Weather Forecasting

Current Weather: Real-time temperature, wind speed, and conditions
Hourly Forecast: 12-hour detailed weather predictions
Daily Forecast: 5-day weather outlook with min/max temperatures
Air Quality Index (AQI): PM2.5, PM10, and US AQI readings

📊 Historical Weather Analysis

Historical Data: Up to 30 days of past weather information
Trend Analysis: Compare current conditions with historical averages
Weather Patterns: Identify temperature and precipitation trends

🏙️ Multi-City Comparison

City Comparison: Compare weather across 2-5 Indian cities simultaneously
Extreme Weather Detection: Identify hottest, coldest, and windiest locations
Temperature Ranges: Calculate temperature differences between cities

🏥 Health & Comfort Indexes

Heat Index: Calculated using temperature and humidity
UV Index: Sun protection recommendations with safety levels
Comfort Level: Personalized comfort assessment
Health Recommendations: Weather-based health advice

🚜 Agricultural Weather Intelligence

Soil Moisture Index: Based on recent rainfall and temperature
Growing Degree Days (GDD): For rice, wheat, and cotton crops
Monsoon Status: Current season identification
Farming Recommendations: Crop-specific weather advice

🛠️ Installation

Prerequisites

Node.js 18+
npm or yarn
TypeScript (for development)

Setup

# Clone the repository
git clone https://github.com/yourusername/Indian-Weather-MCP-Server.git
cd Indian-Weather-MCP-Server.git

# Install dependencies
npm install

# Build the project
npm run build

🚀 Usage

Standalone Server Usage

Direct Server Execution

# Start the MCP server directly
node build/index.js

The server will start and listen for MCP protocol messages via stdio. This is useful for:

Integration with MCP-compatible applications
Direct protocol communication
Server-only deployments

Server Output

🇮🇳 Indian Weather MCP Server running with AQI, Hourly Forecast, Historical Data, Multi-City Comparison, Health Indexes & Agricultural Weather

Client-Server Usage

Interactive Client Mode

# Navigate to client directory
cd client

# Start the interactive client
npm start

Automated Testing Mode

# Navigate to client directory
cd client

# Run automated tests
npm test

Client Features

Real-time Weather Queries: Interactive command-line interface
Automated Testing: Comprehensive test suite for all tools
Error Handling: Graceful error management and reporting
Performance Monitoring: Response time measurements

🛠️ Available Tools

1. Weather Forecast

get_forecast_india(city: string)

Example: Get current weather and forecast for Mumbai

Current temperature, wind speed, and conditions
12-hour hourly forecast
5-day daily forecast
Air quality information

2. Historical Weather

get_historical_weather_india(city: string, days?: number)

Example: Get 7-day historical weather for Delhi

Historical temperature, precipitation, and wind data
Comparison with current conditions
Trend analysis and averages

3. City Comparison

compare_weather_india(cities: string[])

Example: Compare weather between Mumbai, Delhi, and Bangalore

Side-by-side weather comparison
Extreme weather identification
Temperature range analysis

4. Health & Comfort

get_health_comfort_india(city: string)

Example: Get health recommendations for Chennai

Heat index calculation
UV index with protection advice
Air quality health impacts
Personalized comfort level

5. Agricultural Weather

get_agricultural_weather_india(city: string, cropType?: string)

Example: Get farming advice for Punjab with rice crop

Soil moisture assessment
Growing degree days for major crops
Seasonal farming recommendations
Crop-specific weather advice

🎯 Usage Scenarios

Scenario 1: Standalone Server Integration

# Start server for MCP-compatible applications
node build/index.js

Use Cases:

Integration with Claude Desktop
Custom MCP applications
Server-only deployments
API gateway implementations

Scenario 2: Interactive Development & Testing

# Start interactive client for development
cd client
npm start

# Available commands:
forecast Mumbai
historical Delhi 14
compare Mumbai,Delhi,Bangalore
health Chennai
agricultural Punjab rice

Scenario 3: Automated Testing & Validation

# Run comprehensive test suite
cd client
npm test

Test Coverage:

All 5 weather tools
Error handling validation
Performance benchmarking
Response format verification

Scenario 4: Production Deployment

# Build and deploy server
npm run build
node build/index.js

# Or use as system service
pm2 start build/index.js --name weather-mcp

🏗️ Architecture

Project Structure

├── src/                      # Source code
│   ├── config/
│   │   └── constants.ts      # API endpoints and thresholds
│   ├── services/
│   │   ├── geocoding.ts     # City coordinate lookup
│   │   ├── weather-api.ts   # Weather data fetching
│   │   └── weather-processor.ts # Data processing and formatting
│   ├── tools/
│   │   ├── forecast-tool.ts # Weather forecasting
│   │   ├── historical-tool.ts # Historical analysis
│   │   ├── comparison-tool.ts # Multi-city comparison
│   │   ├── health-tool.ts   # Health and comfort
│   │   └── agricultural-tool.ts # Agricultural insights
│   ├── types/
│   │   └── weather.ts       # TypeScript interfaces
│   ├── utils/
│   │   └── calculations.ts  # Weather calculations
│   └── index.ts             # Main server file
├── client/                  # MCP Client
│   ├── index.js            # Interactive client
│   ├── test-client.js      # Automated test suite
│   ├── package.json        # Client dependencies
│   └── README.md           # Client documentation
├── build/                   # Compiled JavaScript
├── package.json            # Server dependencies
└── README.md               # This documentation

Data Sources

Open-Meteo: Weather forecasts and historical data
Open-Meteo Air Quality: Air quality and pollution data
Nominatim: Geocoding for Indian cities

🔧 Configuration

Environment Variables

No API keys required - uses free Open-Meteo APIs.

Customization

Edit src/config/constants.ts to modify:

API endpoints
AQI thresholds
UV index levels
Crop base temperatures
Monsoon season definitions

📊 API Endpoints

The server integrates with multiple Open-Meteo endpoints:

Weather Forecast: https://api.open-meteo.com/v1/forecast
Historical Data: https://archive-api.open-meteo.com/v1/archive
Air Quality: https://air-quality-api.open-meteo.com/v1/air-quality
Geocoding: https://nominatim.openstreetmap.org/search

🧮 Weather Calculations

Heat Index

Uses the National Weather Service formula for heat index calculation based on temperature and humidity.

Growing Degree Days (GDD)

Calculated for different crops:

Rice: Base temperature 10°C
Wheat: Base temperature 0°C
Cotton: Base temperature 15°C

Soil Moisture Index

Based on recent rainfall and average temperature to assess soil moisture levels.

🌍 Supported Cities

All major Indian cities are supported through Nominatim geocoding:

Mumbai, Delhi, Bangalore, Chennai, Kolkata
Hyderabad, Pune, Ahmedabad, Jaipur, Surat
And many more...

🔧 Development

Quick Start

# Clone and setup
git clone https://github.com/yourusername/Indian-Weather-MCP-Server.git
cd Indian-Weather-MCP-Server
npm install
npm run build

# Test the server
cd client
npm install
npm test

Development Workflow

# 1. Make changes to TypeScript files in src/
# 2. Build the project
npm run build

# 3. Test with client
cd client
npm start

# 4. Run automated tests
npm test

Client Development

# Interactive development
cd client
npm run dev  # Auto-restart on changes

# Test specific scenarios
node test-client.js

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes and test them:
```
npm run build
cd client && npm test
```
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

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

🙏 Acknowledgments

Open-Meteo for providing free weather APIs
Nominatim for geocoding services
Model Context Protocol for the MCP framework

📞 Support

Getting Help

GitHub Issues: Create an issue for bugs or feature requests
Documentation: Check both main README and client README
Code Examples: Review the client implementation for usage patterns

Common Issues

Server Won't Start

# Ensure project is built
npm run build

# Check if build directory exists
ls build/

Client Connection Failed

# Ensure server is built first
cd .. && npm run build && cd client

# Test server directly
node ../build/index.js

API Errors

Check internet connection
Verify Open-Meteo API accessibility
Ensure Nominatim geocoding service is available

Performance Tips

Server: Runs efficiently with minimal memory usage
Client: Optimized for fast response times
Caching: Consider implementing response caching for production

Built with ❤️ for Indian weather intelligence

Name		Name	Last commit message	Last commit date
client		client
src		src
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation