agentventure/mcp_server_python_getting_started

Weather MCP Server

A Model Context Protocol (MCP) server that provides weather information and alerts using the National Weather Service (NWS) API. This server offers tools for retrieving weather forecasts and active weather alerts for locations in the United States.

About This Project

This project is based on the Model Context Protocol (MCP) Getting Started Tutorial for server developers. The tutorial provides a comprehensive guide for building MCP servers and integrating them with clients like Claude for Desktop.

The original code sample for this weather server can be found in the MCP Quickstart Resources repository.

Features

• Weather Alerts: Get active weather alerts for any US state using two-letter state codes
• Weather Forecasts: Retrieve detailed weather forecasts for specific coordinates
• Real-time Data: Uses the official National Weather Service API for accurate, up-to-date information
• Easy Integration: Simple MCP server that can be integrated with any MCP-compatible client

Installation

Prerequisites

• Python 3.8 or higher
• uv package manager (recommended) or pip

Setup

1. Clone the repository:

git clone https://github.com/agentventure/mcp_server_python_getting_started.git
cd mcp_server_python_getting_started

2. Install dependencies using uv:

uv sync

Or using pip:

pip install -r requirements.txt

Usage

Running the Server

Start the MCP server:

uv run weather.py

The server will start and communicate via stdio, ready to handle requests from MCP clients.

Available Tools

1. Get Weather Alerts (get_alerts)

Retrieve active weather alerts for a US state.

Parameters:

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

Example:

# Get alerts for California
alerts = await get_alerts("CA")

Response Format:

Event: Severe Thunderstorm Warning
Area: Northern California
Severity: Severe
Description: Severe thunderstorm warning in effect...
Instructions: Take shelter immediately...

---

Event: Flood Watch
Area: Central Valley
Severity: Moderate
Description: Flood watch in effect...
Instructions: Monitor weather conditions...

2. Get Weather Forecast (get_forecast)

Get detailed weather forecast for a specific location.

Parameters:

• latitude (float): Latitude coordinate of the location
• longitude (float): Longitude coordinate of the location

Example:

# Get forecast for San Francisco (37.7749, -122.4194)
forecast = await get_forecast(37.7749, -122.4194)

Response Format:

Tonight:
Temperature: 55°F
Wind: 10 mph NW
Forecast: Clear skies with light winds. Low around 55.

---

Tomorrow:
Temperature: 68°F
Wind: 15 mph W
Forecast: Sunny with increasing clouds in the afternoon. High near 68.

---

Tomorrow Night:
Temperature: 52°F
Wind: 8 mph NW
Forecast: Partly cloudy with light winds. Low around 52.

API Information

This server uses the National Weather Service API, which provides:

• No API Key Required: Free access to weather data
• Real-time Updates: Data is updated frequently throughout the day
• Comprehensive Coverage: Covers all US states and territories
• Reliable Service: Official government weather service

Data Sources

• Alerts: Active weather alerts from the NWS
• Forecasts: Detailed weather forecasts including temperature, wind, and conditions
• Geographic Data: Point-based weather information for any US location

Error Handling

The server includes robust error handling for:

• Network connectivity issues
• Invalid coordinates or state codes
• API service unavailability
• Timeout conditions

When errors occur, the server returns informative error messages to help with debugging.

Development

Project Structure

weather/
├── weather.py          # Main MCP server implementation
├── main.py            # Entry point for running the server
├── pyproject.toml     # Project configuration and dependencies
├── README.md          # This file
└── .gitignore         # Git ignore rules

Dependencies

• mcp: Model Context Protocol server framework
• httpx: Async HTTP client for API requests
• fastmcp: FastMCP server implementation

Adding New Features

To add new weather-related tools:

1. Create a new async function in weather.py
2. Decorate it with @mcp.tool()
3. Add proper type hints and docstrings
4. Implement error handling using the existing make_nws_request helper

Contributing

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

License

This project is open source and available under the MIT License.

Support

For issues or questions:

1. Check the National Weather Service API documentation
2. Review the MCP documentation at modelcontextprotocol.io
3. Open an issue in this repository

Note: This server is designed for educational and development purposes. For production use, consider implementing rate limiting and additional error handling based on your specific requirements.