Simple Weather MCP Server

A simplified Model Context Protocol (MCP) server that provides weather data through integration with the National Weather Service API, designed to work with AI language models like Google's Gemini.

Features

• Weather Forecasts: Get detailed weather forecasts for any location using latitude/longitude coordinates
• Weather Alerts: Retrieve active weather alerts for US states
• MCP Protocol: Implements JSON-RPC 2.0 based Model Context Protocol for AI integration
• Cross-platform: Works on Windows, macOS, and Linux
• No External Dependencies: Uses Python standard library only (urllib instead of external HTTP libraries)

Files

• weather_simple.py - The MCP weather server implementation
• client_simple.py - Simplified MCP client with Gemini API integration
• test_simple.py - Test script to verify server functionality

Requirements

• Python 3.8 or higher
• Google Gemini API key (for client usage)
• Internet connection (for National Weather Service API access)

Installation

1. Clone or download the project files
2. No additional Python packages required - uses standard library only
3. Set your Gemini API key:

   export GEMINI_API_KEY="your-api-key-here"

Usage

Testing the Server

First, test that the server works correctly:

python test_simple.py

Expected output:

✓ Server started successfully
✓ Server initialization successful  
✓ Found 2 tools:
   - get_alerts: Get weather alerts for a US state.
   - get_forecast: Get weather forecast for a location.

Running the Client

Start the interactive client:

python client_simple.py

Connecting to Weather Server

In the client interface:

simple-mcp> /connect weather python weather_simple.py

Available Commands

• /connect <name> <command...> - Connect to MCP server
• /disconnect <name> - Disconnect from server
• /list <name> - List available tools
• /call <name> <tool> <json_args> - Call a specific tool
• /servers - List connected servers
• /quit - Exit client

Tool Examples

Get Weather Forecast

simple-mcp> /call weather get_forecast {"latitude": 40.7128, "longitude": -74.0060}

Get Weather Alerts

simple-mcp> /call weather get_alerts {"state": "NY"}

Natural Language Queries

Once connected, you can ask natural language questions:

simple-mcp> What's the weather forecast for New York City?
simple-mcp> Are there any weather alerts for California?

API Details

Available Tools

get_forecast

Gets weather forecast for a specific location.

Parameters:

• latitude (float): Latitude coordinate
• longitude (float): Longitude coordinate

Returns: Formatted weather forecast text

get_alerts

Gets active weather alerts for a US state.

Parameters:

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

Returns: Formatted weather alerts text

Data Source

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

• Free access to US weather data
• No API key required
• Reliable, official weather information
• Coverage for all US states and territories

Architecture

The server implements a simplified version of the Model Context Protocol:

• JSON-RPC 2.0: Standard protocol for communication
• Stdio Transport: Communication via standard input/output
• Async Processing: Non-blocking request handling
• Error Handling: Graceful handling of network and API errors

Troubleshooting

Server Won't Start

• Ensure Python 3.8+ is installed
• Check that no other process is using the same ports
• Verify internet connectivity for NWS API access

Connection Timeouts

• The server may take a few seconds to start
• Check firewall settings if running across network
• Ensure the server process hasn't crashed (check stderr output)

API Errors

• NWS API may be temporarily unavailable
• Some coordinates may be outside NWS coverage area
• Invalid state codes will return no results

Client Issues

• Ensure GEMINI_API_KEY environment variable is set
• Check that Gemini API key is valid and has quota remaining
• Verify network connectivity for both NWS and Gemini APIs

Limitations

• US Only: National Weather Service API only covers US locations
• Coordinate Precision: NWS API requires fairly precise coordinates
• Rate Limiting: NWS API has undocumented rate limits
• Forecast Range: Limited to 5-day forecast periods

Development

Extending the Server

To add new tools, follow this pattern in weather_simple.py:

@server.tool("tool_name")
async def tool_function(param1: str, param2: float) -> str:
    """Tool description for AI context.
    
    Args:
        param1: Description of parameter
        param2: Description of parameter
    """
    # Implementation here
    return "Result string"

Custom Clients

The server implements standard JSON-RPC 2.0 over stdio, so you can create custom clients in any language. Key methods:

• initialize - Start session
• tools/list - Get available tools
• tools/call - Execute a tool

License

This project is provided as-is for educational and development purposes. The National Weather Service API is a public service provided by NOAA.