Abishek-Raj-M/weather-mcp-server

Weather MCP Tool

A Model Context Protocol (MCP) server that provides real-time weather information using WeatherAPI.com. This tool allows GitHub Copilot to access weather data through a local MCP server built with Python, Flask, and Fast MCP.

Features

• Real-time Weather Data: Current weather conditions for any location
• Weather Forecasts: 1-10 day weather forecasts with alerts
• Location Search: Find locations by name or coordinates
• Weather Alerts: Active weather warnings and alerts
• Caching: Intelligent caching to respect API rate limits
• MCP Integration: Full Model Context Protocol support for GitHub Copilot

Quick Start

TL;DR: After setup, run python run.py --flask for HTTP server or python run.py for MCP mode.

1. Setup Virtual Environment

# Navigate to project directory
cd weather-mcp-tool

# Create virtual environment (REQUIRED)
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Verify activation (should show (venv) in prompt)

2. Install Dependencies

# Upgrade pip
python -m pip install --upgrade pip

# Install core dependencies
pip install -r requirements.txt

# Install development dependencies (optional)
pip install -r requirements-dev.txt

3. Configure Environment

# Copy environment template
copy .env.example .env  # Windows
# cp .env.example .env  # macOS/Linux

# Edit .env with your configuration
# WEATHER_API_KEY=1401cb7b45b742bab23105426252509

4. Run the Server

# Start MCP server (default mode)
python run.py

# Or start Flask HTTP server
python run.py --flask

Available Tools

get_current_weather

Get current weather conditions for any location.

# Example usage in Copilot
# "What's the current weather in New York?"

Parameters:

• location (str): City name, coordinates, or location identifier
• include_air_quality (bool): Include air quality data (default: False)

get_weather_forecast

Get weather forecast for 1-10 days.

# Example usage in Copilot  
# "Can you get me a 7-day weather forecast for London?"

Parameters:

• location (str): City name, coordinates, or location identifier
• days (int): Number of forecast days (1-10, default: 3)
• include_alerts (bool): Include weather alerts (default: False)

search_locations

Search for locations by name or coordinates.

# Example usage in Copilot
# "Find weather stations near coordinates 40.7128,-74.0060"

Parameters:

• query (str): Location search query

get_weather_alerts

Get active weather alerts and warnings.

# Example usage in Copilot
# "Are there any weather alerts for Miami today?"

Parameters:

• location (str): City name, coordinates, or location identifier

Configuration

Environment Variables (.env file)

# Weather API Configuration
WEATHER_API_KEY=your_api_key_here
WEATHER_API_BASE_URL=https://api.weatherapi.com/v1

# MCP Server Configuration  
MCP_SERVER_PORT=5000
MCP_SERVER_HOST=localhost

# Logging Configuration
LOG_LEVEL=INFO

# Caching Configuration
CACHE_TTL=900  # 15 minutes

GitHub Copilot Integration

Create ~/.config/github-copilot/mcp.json:

{
  "servers": {
    "weather": {
      "command": "path/to/weather-mcp-tool/venv/Scripts/python",
      "args": ["path/to/weather-mcp-tool/src/main.py"],
      "cwd": "path/to/weather-mcp-tool",
      "env": {
        "WEATHER_API_KEY": "1401cb7b45b742bab23105426252509"
      }
    }
  }
}

Development

Running Tests

# Ensure virtual environment is activated
source venv/bin/activate  # or venv\Scripts\activate

# Run all tests
pytest

# Run with coverage
pytest --cov=src

# Run specific test file
pytest tests/test_weather_service.py -v

Code Quality

# Format code
black src/

# Lint code  
flake8 src/

# Type checking
mypy src/

# Sort imports
isort src/

Development Server

# Run Flask development server
python run.py --flask

# Run MCP server (for GitHub Copilot integration)
python run.py

API Endpoints (Flask Mode)

When running in Flask mode (--flask or RUN_MODE=flask):

• GET / - Service information
• GET /health - Health check
• GET /tools - List available MCP tools
• GET /stats - Service statistics and cache info

Project Structure

weather-mcp-tool/
├── venv/                     # Virtual environment
├── src/
│   ├── __init__.py          # Package initialization
│   ├── main.py              # Main MCP server entry point  
│   ├── weather_service.py   # Weather API service
│   ├── tools.py             # MCP tool definitions
│   └── models.py            # Pydantic models
├── tests/
│   ├── test_weather_service.py
│   ├── test_tools.py
│   └── test_integration.py
├── .env                     # Environment variables
├── .env.example             # Environment template
├── requirements.txt         # Core dependencies
├── requirements-dev.txt     # Development dependencies
├── pyproject.toml          # Python project config
└── README.md               # This file

Dependencies

Core Dependencies (requirements.txt)

• mcp>=1.0.0 - Model Context Protocol framework
• flask>=2.3.0 - Web framework for HTTP endpoints
• requests>=2.31.0 - HTTP client for API calls
• python-dotenv>=1.0.0 - Environment variable management
• pydantic>=2.5.0 - Data validation and serialization
• uvicorn>=0.24.0 - ASGI server
• gunicorn>=21.2.0 - WSGI server

Development Dependencies (requirements-dev.txt)

• pytest>=7.4.0 - Testing framework
• pytest-cov>=4.1.0 - Coverage reporting
• black>=23.9.0 - Code formatting
• flake8>=6.1.0 - Code linting
• mypy>=1.6.0 - Type checking

Error Handling

The system includes comprehensive error handling:

• API Errors: Weather API connectivity issues
• Validation Errors: Invalid parameters or data
• Network Errors: Timeout and connection issues
• Configuration Errors: Missing API keys or invalid settings

All errors are properly logged and return structured error responses.

Caching

The weather service implements intelligent caching:

• Cache TTL: 15 minutes for weather data (configurable)
• Alert Cache: 5 minutes for weather alerts
• Location Cache: Uses standard TTL (locations don't change often)
• Memory Cache: Simple in-memory cache (can be extended to Redis)

Rate Limiting

Respects WeatherAPI.com rate limits:

• Free tier: 1 million calls per month
• Caching reduces actual API calls
• Built-in request deduplication

Security

• API Key Protection: Stored in .env file, never in code
• Input Validation: All inputs validated and sanitized
• Error Handling: No sensitive data in error responses
• Environment Isolation: Uses virtual environment

Troubleshooting

Common Issues

1. Import Error for Flask/MCP:

   • Ensure virtual environment is activated
   • Run pip install -r requirements.txt

2. API Key Error:

   • Check .env file exists and contains WEATHER_API_KEY
   • Verify API key is valid

3. Connection Error:

   • Check internet connectivity
   • Verify WeatherAPI.com is accessible

4. Port Already in Use:

   • Change MCP_SERVER_PORT in .env file
   • Or kill process using the port

Debug Mode

Enable debug logging:

LOG_LEVEL=DEBUG python src/main.py

Health Check

Test server health:

# MCP mode - check logs
python src/main.py

# Flask mode - HTTP endpoint
curl http://localhost:5000/health

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Run quality checks: black, flake8, mypy, pytest
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Additional Documentation

• - Complete guide for integrating with GitHub Copilot
• - Production deployment guide with Docker, systemd, and monitoring
• - Configuration file templates

Support

For issues and questions:

1. Check the troubleshooting section
2. Review logs for error details
3. Check the additional documentation guides
4. Open an issue with:
   • Error messages
   • Environment details
   • Steps to reproduce