Weather MCP Server

A Model Context Protocol (MCP) server that provides weather information and alerts from the National Weather Service (NWS).

Features

get_alerts: Retrieve active weather alerts for a US state
get_forecast: Get weather forecasts for a specific location (latitude/longitude)

Prerequisites

Python 3.10 or higher
Docker and Docker Compose (for containerized deployment)

Installation

Local Setup

# Clone the repository
git clone https://github.com/yourusername/weather-mcp.git
cd weather-mcp

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

# Run the server
weather-mcp

Docker Setup

# Build and run with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f weather-mcp

Configuration

Claude Desktop Integration

To use this server with Claude Desktop, add the following to ~/.config/Claude/claude_desktop_config.json (Linux/macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Option 1: Local Installation

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/weather-mcp",
        "run",
        "-m",
        "weather.main"
      ]
    }
  }
}

Option 2: Docker Container

{
  "mcpServers": {
    "weather": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "weather-mcp-server"
      ]
    }
  }
}

Development

Running Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=src/weather

Code Formatting and Linting

# Format code with Black
black src tests

# Lint with Ruff
ruff check src tests

Project Structure

weather-mcp/
├── src/weather/              # Main package
│   ├── __init__.py
│   ├── main.py              # Entry point
│   └── server.py            # Server implementation
├── config/                   # Configuration files
│   ├── __init__.py
│   └── settings.py
├── tests/                    # Test suite
├── Dockerfile               # Docker image definition
├── docker-compose.yml       # Docker Compose configuration
├── pyproject.toml          # Project metadata and dependencies
├── README.md               # This file
└── DOCKER_SETUP.md         # Docker setup guide

API Reference

get_alerts(state: str) -> str

Get active weather alerts for a US state.

Parameters:

state: Two-letter US state code (e.g., CA, NY, TX)

Returns: Formatted string containing active weather alerts or a message if none found.

get_forecast(latitude: float, longitude: float) -> str

Get weather forecast for a specific location.

Parameters:

latitude: Location latitude (up to 4 decimal places recommended)
longitude: Location longitude (up to 4 decimal places recommended)

Returns: Formatted string with the next 5 forecast periods including temperature, wind, and conditions.

Troubleshooting

Server won't start

Check Python version: python --version (requires 3.10+)
Ensure dependencies are installed: pip install -e .
Check logs for detailed error messages

Docker issues

Rebuild image: docker-compose build --no-cache
View logs: docker-compose logs weather-mcp
Ensure Docker daemon is running

Claude Desktop not detecting server

Verify the path in claude_desktop_config.json
Restart Claude Desktop after configuration changes
Check the MCP server settings in Claude Desktop

Logging

The server logs to stderr to avoid interfering with the MCP protocol's use of stdout. Logs are automatically sent to stderr and include timestamps and severity levels.

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues, questions, or suggestions, please open an issue on GitHub.

Weather MCP Server