vlbezak/weather-mcp

Weather MCP Server

A Model Context Protocol (MCP) server that provides comprehensive weather information using the FastMCP framework.

🌟 Features

• Current Weather: Get real-time weather data for any city worldwide
• Weather Forecasts: 5-day weather forecasts with 3-hour intervals
• Weather Alerts: US weather alerts from the National Weather Service
• Robust Error Handling: Comprehensive error handling and validation
• Type Safety: Full type hints and Pydantic models
• Comprehensive Testing: Test coverage for all components
• Configurable: Environment-based configuration

🚀 Quick Start

Prerequisites

• Python 3.10 or higher
• UV package manager
• OpenWeatherMap API key (free at openweathermap.org)

Installation

1. Clone the repository:

   git clone <repository-url>
   cd weather-mcp
   

2. Install UV (if not already installed):

   curl -LsSf https://astral.sh/uv/install.sh | sh
   source $HOME/.local/bin/env
   

3. Install dependencies:

   uv sync --dev
   

4. Set up environment variables:

   # Create .env file
   echo "OPENWEATHER_API_KEY=your_api_key_here" > .env
   
   # Or export directly
   export OPENWEATHER_API_KEY="your_api_key_here"
   

5. Test the installation:

   uv run python -m weather_mcp.main
   

Get Your API Key

1. Go to OpenWeatherMap
2. Sign up for a free account
3. Navigate to API Keys section
4. Copy your API key

🛠️ Available Tools

The Weather MCP Server provides the following tools:

get_current_weather(city, country_code?)

Get current weather information for a city.

Parameters:

• city (string, required): Name of the city
• country_code (string, optional): ISO country code (e.g., 'US', 'GB', 'CA')

Example:

get_current_weather("London", "GB")
get_current_weather("New York")

get_weather_forecast(city, days?, country_code?)

Get weather forecast for a city.

Parameters:

• city (string, required): Name of the city
• days (integer, optional): Number of days (1-5, default: 5)
• country_code (string, optional): ISO country code

Example:

get_weather_forecast("Paris", 3, "FR")
get_weather_forecast("Tokyo")

get_weather_alerts(state_code)

Get weather alerts for a US state (no API key required).

Parameters:

• state_code (string, required): Two-letter US state code

Example:

get_weather_alerts("CA")
get_weather_alerts("FL")

get_server_info()

Get server information and configuration status.

test_api_connection()

Test API connections and validate configuration.

⚙️ Configuration

The server can be configured using environment variables:

*Required for current weather and forecast features. Weather alerts work without an API key.

Example .env file:

OPENWEATHER_API_KEY=your_api_key_here
DEBUG=true
API_TIMEOUT=45.0
MAX_RETRIES=2

🏃‍♂️ Running the Server

Standalone Mode

uv run python -m weather_mcp.main

With Environment Variables

OPENWEATHER_API_KEY="your_key" uv run python -m weather_mcp.main

Production Mode

uv run python -m weather_mcp.main --transport stdio

🧪 Development

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src --cov-report=html

# Run specific test file
uv run pytest src/weather_mcp/features/weather/tests/test_models.py -v

# Run model tests only
uv run pytest -k "test_models" -v

Code Quality

# Format code
uv run ruff format .

# Lint code
uv run ruff check .

# Fix linting issues
uv run ruff check --fix .

# Type checking
uv run mypy src/

Pre-commit Hooks

# Install pre-commit hooks
uv run pre-commit install

# Run hooks manually
uv run pre-commit run --all-files

📁 Project Structure

weather-mcp/
├── src/weather_mcp/
│   ├── __init__.py
│   ├── main.py                 # Main MCP server
│   ├── core/
│   │   ├── __init__.py
│   │   ├── config.py           # Configuration management
│   │   ├── exceptions.py       # Custom exceptions
│   │   └── http_client.py      # HTTP client
│   ├── features/
│   │   └── weather/
│   │       ├── __init__.py
│   │       ├── models.py       # Pydantic models
│   │       ├── service.py      # Weather service
│   │       └── tests/
│   │           ├── test_models.py
│   │           └── test_service.py
│   └── tests/
│       ├── __init__.py
│       └── conftest.py         # Shared fixtures
├── pyproject.toml              # Project configuration
├── README.md
├── .env.example               # Environment template
└── .gitignore

🔌 Integration with Claude Desktop

To use this server with Claude Desktop, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["/path/to/your/weather-mcp/src/weather_mcp/main.py"],
      "env": {
        "OPENWEATHER_API_KEY": "your_api_key_here"
      }
    }
  }
}

Configuration File Locations

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

📊 Example Usage

Current Weather

# Get current weather for London
get_current_weather("London", "GB")

# Output:
🌤️ Weather in London:
🌡️ Temperature: 15.5°C (feels like 14.8°C)
🌦️ Condition: Clear Sky
💧 Humidity: 65%
📊 Pressure: 1013 hPa
💨 Wind: 3.2 m/s (230°)
👁️ Visibility: 10.0 km

Weather Forecast

# Get 3-day forecast for Paris
get_weather_forecast("Paris", 3, "FR")

# Output:
📅 Weather forecast for Paris:

📍 2023-11-15 12:00 | 🌡️ 15.5°C | 🌦️ Clear Sky | ☔ 10% chance of rain
📍 2023-11-16 12:00 | 🌡️ 12.3°C | 🌦️ Few Clouds | ☔ 20% chance of rain
📍 2023-11-17 12:00 | 🌡️ 18.1°C | 🌦️ Partly Cloudy | ☔ 5% chance of rain

Weather Alerts

# Get weather alerts for California
get_weather_alerts("CA")

# Output:
🚨 Weather alerts for CA:

Alert 1:
🚨 High Wind Warning
📢 Sender: NWS Los Angeles/Oxnard CA
⏰ 2023-11-15 15:00 - 2023-11-16 06:00
📝 Strong gusty winds are expected across the mountains and foothills...

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following the code style guidelines
4. Add tests for new functionality
5. Ensure tests pass (uv run pytest)
6. Lint and format code (uv run ruff check --fix . and uv run ruff format .)
7. Commit your changes (git commit -m 'Add amazing feature')
8. Push to the branch (git push origin feature/amazing-feature)
9. Open a Pull Request

📝 License

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

🙏 Acknowledgments

• FastMCP - Fast MCP server framework
• OpenWeatherMap - Weather data API
• National Weather Service - Weather alerts API
• UV - Fast Python package manager
• Pydantic - Data validation library

🐛 Troubleshooting

Common Issues

"OpenWeatherMap API key not configured"

• Make sure your API key is set in the OPENWEATHER_API_KEY environment variable
• Check that your .env file is in the correct location
• Verify your API key is valid at OpenWeatherMap

"City not found"

• Check the spelling of the city name
• Try adding a country code parameter
• Use the format "City Name, Country Code" (e.g., "London, GB")

"API request timeout"

• Check your internet connection
• Increase the API_TIMEOUT environment variable
• Verify the API endpoints are accessible

Tests failing

• Make sure all dependencies are installed: uv sync --dev
• Check that you're in the correct directory
• Run tests with verbose output: uv run pytest -v

For more issues, please check the Issues page or create a new issue.

📞 Support

If you need help or have questions:

1. Check the FAQ section above
2. Search existing Issues
3. Create a new issue with a detailed description
4. Join our Discord community (coming soon)

Made with ❤️ using FastMCP and modern Python practices