Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/kode-rex/clima

A simple National Weather Service MCP server
https://github.com/kode-rex/clima

Last synced: 10 months ago
JSON representation

A simple National Weather Service MCP server

Awesome Lists containing this project

README 

          
# Weather MCP - National Weather Service Edition



A comprehensive Model Context Protocol (MCP) server that provides **completely free** weather data using the National Weather Service API. Built with FastMCP for modern AI assistant integration.



## Features



### Core Weather Features

- **Zero Cost**: Completely free weather data from the US Government

- **No API Keys**: No registration or authentication required

- **FastMCP Integration**: Modern MCP server using FastMCP framework

- **National Weather Service API**: Reliable, official US government weather data

- **Real-time Updates**: SSE support for live weather data streams

- **Weather Alerts**: Free real-time weather alerts and warnings

- **Comprehensive Coverage**: Current weather, forecasts, and alerts

- **FastMCP SSE Transport**: Single unified server with SSE transport for API integration



### Development Features

- **Modern Python**: Built with Python 3.11+ and modern tooling

- **Type Safety**: Full type hints with MyPy validation

- **Code Quality**: Automated formatting (Black) and linting (Ruff)

- **Comprehensive Testing**: 56+ tests with pytest and async support

- **Docker Support**: Container-ready with docker-compose

- **CI/CD Pipeline**: GitHub Actions for automated testing and quality checks

- **Developer Experience**: Makefile with convenient development commands

- **Modular Architecture**: Clean service layer with individual test files



## Installation



### Quick Start



1. **Clone the repository**:

   ```bash

   git clone 

   cd clima-mcp

   ```



2. **Install dependencies**:

   ```bash

   pip install -e ".[dev]"

   ```



3. **Set up development environment** (optional):

   ```bash

   make dev-setup

   ```



4. **That's it!** No API keys needed - the National Weather Service API is completely free.



### Alternative Installation Methods



#### Using Docker:

```bash

# Quick start

docker-compose up --build



# Or using Makefile

make docker-run

```



#### Using Makefile (recommended for development):

```bash

make install-dev

make dev-setup

```



## Usage



### Test the API (Recommended First Step)



```bash

clima-mcp test

# or

make run-test

```



You should see:

```

✓ Location search successful: 10001, Manhattan

✓ Current weather: 81.0°F, Clear

✓ 5-day forecast: 5 days retrieved

✓ Weather alerts: 1 active alerts

🎉 All NWS API tests passed!

```



### FastMCP Server with SSE Transport



Run the unified FastMCP server with SSE transport for API integration:



```bash

clima-mcp run

# or

make run

```



The server starts on `http://localhost:8000` with FastMCP SSE transport, providing 4 weather tools accessible via HTTP/SSE for integration with OpenAI and other AI services.



### Test the Server



Open the interactive test client:

```bash

open examples/sse_client.html

```



## Weather Tools



The FastMCP server provides 4 weather tools for API integration:



### Core Tools



- **`get_weather(zip_code)`**: Get current weather conditions for a ZIP code

- **`get_forecast(zip_code, days=5)`**: Get weather forecast (1-7 days)

- **`get_alerts(zip_code)`**: Get active weather alerts (completely free!)

- **`search_locations(query)`**: Search for locations by name or ZIP code



### API Integration



Perfect for **OpenAI function calling** and other AI service integrations:



```python

# Example OpenAI function call

tools = [

    {

        "type": "function",

        "function": {

            "name": "get_weather",

            "description": "Get current weather for a ZIP code",

            "parameters": {

                "type": "object",

                "properties": {

                    "zip_code": {"type": "string", "description": "ZIP code (e.g., '10001')"}

                },

                "required": ["zip_code"]

            }

        }

    }

]

```



## FastMCP SSE Integration



The server uses **FastMCP with SSE transport** for real-time API integration:



### Connection

```

Server: http://localhost:8000

Transport: SSE (Server-Sent Events)

Protocol: FastMCP

```



### Tool Calls

Tools are accessible via FastMCP protocol over SSE. Perfect for:

- **OpenAI function calling**

- **Claude tool use**

- **Custom AI integrations**

- **Real-time weather APIs**



### Interactive Testing

Start the server and navigate to the test client:

```bash

clima-mcp run

# Then open: http://localhost:8000/

```



![Clima Demo Interface](docs/images/clima-demo-screenshot.png)



*The interactive test client showing real-time weather data for Erie, CO*



Features:

- Test all 4 weather tools

- Real-time responses

- Mock data demonstrations

- API integration examples



## Example Usage



### Python MCP Client



```python

from weather_mcp import NationalWeatherServiceClient



async with NationalWeatherServiceClient() as client:

    # Search by zip code

    locations = await client.search_locations("10001")

    location_key = locations[0]["Key"]



    # Get current weather

    weather = await client.get_current_weather(location_key)

    print(f"Temperature: {weather.temperature}°{weather.temperature_unit}")



    # Get alerts (completely free!)

    alerts = await client.get_weather_alerts(location_key)

    print(f"Active alerts: {len(alerts)}")

```



### JavaScript SSE Client



```javascript

const eventSource = new EventSource('http://localhost:8000/weather/stream/10001');



eventSource.addEventListener('weather_update', function(event) {

    const data = JSON.parse(event.data);

    console.log(`Temperature: ${data.weather.temperature}°F`);

});



eventSource.addEventListener('weather_alert', function(event) {

    const data = JSON.parse(event.data);

    console.log(`Weather Alert: ${data.alerts[0].title}`);

});

```



## Coverage Area



The National Weather Service provides comprehensive coverage for:

- 🇺🇸 **United States** (all 50 states and territories)

- **ZIP codes** supported for easy location lookup

- **Coordinates** for precise location targeting

- **Puerto Rico, US Virgin Islands, Guam** and other US territories



## Architecture



```

main.py (Legacy entry point - use CLI instead)

├── weather_mcp/

│   ├── cli.py (Main CLI with FastMCP SSE server)

│   ├── api_tools.py (FastMCP weather tools)

│   ├── nws.py (National Weather Service client)

│   ├── config.py (Configuration management)

│   ├── models.py (Pydantic data models)

│   ├── exceptions.py (Custom exceptions)

│   └── services/ (Service layer architecture)

│       ├── location_service.py

│       ├── weather_service.py

│       ├── forecast_service.py

│       ├── alert_service.py

│       ├── raw_weather_service.py

│       └── testing_service.py

├── tests/ (Comprehensive test suite)

│   ├── test_location_service.py

│   ├── test_weather_service.py

│   ├── test_forecast_service.py

│   ├── test_alert_service.py

│   ├── test_raw_weather_service.py

│   ├── test_testing_service.py

│   ├── test_weather_config.py

│   └── test_weather_server.py

├── examples/

│   └── sse_client.html (FastMCP test client)

├── .github/workflows/ (CI/CD pipelines)

├── Dockerfile & docker-compose.yml

├── pyproject.toml (Modern Python project config)

├── Makefile (Development commands)

└── .pre-commit-config.yaml (Code quality automation)

```



### Service Layer Architecture



The application follows a clean service-oriented architecture:



- **CLI**: Modern FastMCP server with SSE transport

- **API Tools**: 4 weather functions for external integration

- **Services**: Business logic for weather operations

- **Models**: Pydantic data validation and serialization

- **Configuration**: Environment-based settings management

- **Exception Handling**: Custom exceptions for better error management



### Modern Python Project Structure



The project uses modern Python packaging and tooling:



- **pyproject.toml**: Modern Python project configuration

- **Ruff**: Fast linting and code formatting

- **MyPy**: Static type checking

- **Pre-commit**: Automated quality checks

- **GitHub Actions**: CI/CD with testing and security scanning

- **Docker**: Containerized deployment options



## Technical Details



### Data Sources



- **Current Weather**: NWS observation stations

- **Forecasts**: NWS gridded forecast data

- **Alerts**: NWS weather alerts and warnings

- **Location Data**: OpenStreetMap Nominatim geocoding



### Performance



- **No Rate Limits**: Government API with no request restrictions

- **Caching**: Built-in caching for optimal performance

- **Async**: Full async/await support for concurrent requests

- **Real-time**: SSE streaming for live updates



### Reliability



- **Government Source**: Official US National Weather Service data

- **High Availability**: Government-maintained infrastructure

- **No API Keys**: No authentication failures or key expiration

- **Comprehensive Error Handling**: Graceful degradation on failures



## Configuration



The server can be configured through environment variables or a `.env` file:



```bash

# Server Configuration

HOST=localhost

PORT=8000

DEBUG=false

LOG_LEVEL=INFO



# SSE Configuration

SSE_HEARTBEAT_INTERVAL=30

SSE_MAX_CONNECTIONS=100

SSE_CONNECTION_TIMEOUT=300



# Cache Configuration

CACHE_TTL_SECONDS=300

CACHE_MAX_SIZE=1000

```



## Development & Testing



### Quick Development Commands



The project includes a comprehensive `Makefile` for easy development:



```bash

# Development setup

make dev-setup          # Full development environment setup

make install-dev         # Install with development dependencies



# Code quality

make format             # Format code with Black and Ruff

make lint               # Run linting checks

make type-check         # Run MyPy type checking

make pre-commit         # Run pre-commit hooks



# Testing

make test              # Run all tests

make test-unit         # Run unit tests only

make test-integration  # Run integration tests only

make coverage          # Run tests with coverage report



# Application

make run-test          # Test the NWS API

make run               # Run FastMCP server with SSE transport



# Docker

make docker-build      # Build Docker image

make docker-run        # Run server in Docker container

make run-docker-dev    # Start development mode with hot reload

make docker-logs       # View Docker logs

make docker-stop       # Stop Docker containers



# Cleanup

make clean             # Clean build artifacts

```



### Traditional Testing



Run the comprehensive test suite:



```bash

python run_tests.py

```



With options:

```bash

python run_tests.py --type unit --coverage --verbose

python run_tests.py --type integration --fail-fast

python run_tests.py --parallel 4

```



**Test Coverage**:

- Unit tests for all weather services (individual service test files)

- Integration tests for MCP and SSE servers

- Configuration validation tests

- Mock API responses for CI/CD

- 56 comprehensive tests with modular structure



### Code Quality Tools



The project uses modern Python development tools:



- **Black**: Code formatting

- **Ruff**: Fast linting and import sorting

- **MyPy**: Static type checking

- **Pre-commit hooks**: Automated quality checks

- **Pytest**: Testing framework with async support

- **GitHub Actions**: Automated CI/CD pipeline



### Development Workflow



1. **Set up environment**:

   ```bash

   make dev-setup

   ```



2. **Make changes and test**:

   ```bash

   make format

   make lint

   make test

   ```



3. **Commit changes** (pre-commit hooks run automatically):

   ```bash

   git add .

   git commit -m "Your changes"

   ```



### Docker Development



Run with Docker for consistent environment:



```bash

# Production mode

docker-compose up



# Development mode with hot reload

docker-compose --profile dev up

```



## Contributing



We welcome contributions! The project includes comprehensive development tools to make contributing easy.



### Development Setup



1. **Fork and clone the repository**

2. **Set up development environment**:

   ```bash

   make dev-setup

   ```

3. **Make your changes**

4. **Run quality checks**:

   ```bash

   make format        # Format code

   make lint          # Check linting

   make type-check    # Type checking

   make test          # Run tests

   ```

5. **Commit and push** (pre-commit hooks ensure quality)

6. **Submit a pull request**



### Code Quality Standards



- **Type hints** required for all functions

- **Docstrings** for all public methods

- **Tests** for new functionality

- **Code formatting** with Black

- **Linting** compliance with Ruff

- **100% test coverage** for new features



### Continuous Integration



The project uses GitHub Actions for:

- **Automated testing** on Python 3.11

- **Code quality checks** (formatting, linting, type checking)

- **Security scanning** with Bandit

- **Coverage reporting** to Codecov

- **Docker builds** validation



### Project Structure



- Follow the existing service layer architecture

- Add tests for each new service in corresponding test files

- Update documentation for new features

- Use the custom exception classes for error handling



## License



MIT License - see LICENSE file for details.



## Support



For issues and questions:

- Review the [National Weather Service API documentation](https://www.weather.gov/documentation/services-web-api)

- Check the [Model Context Protocol specification](https://modelcontextprotocol.io/)

- Open an issue in this repository



## Badges



![Tests](https://github.com/your-org/clima-mcp/workflows/CI/badge.svg)

![Python](https://img.shields.io/badge/python-3.11%2B-blue)

![Code style](https://img.shields.io/badge/code%20style-black-000000.svg)

![Type checked](https://img.shields.io/badge/mypy-checked-blue)

![License](https://img.shields.io/badge/license-MIT-green)



## Acknowledgments



- [National Weather Service](https://www.weather.gov/) for providing free, reliable weather data

- [Model Context Protocol](https://modelcontextprotocol.io/) for the protocol specification

- [FastMCP](https://github.com/jlowin/fastmcp) for the modern MCP framework

- [OpenStreetMap](https://www.openstreetmap.org/) for geocoding services

- Python community for excellent development tools (Black, Ruff, MyPy, Pytest)