Weather MCP Server
A Model Context Protocol (MCP) server that provides weather information using the National Weather Service API. This server exposes tools for getting weather forecasts and alerts for US locations.
Features
- 🌤️ Weather Forecasts: Get detailed weather forecasts for any US location using latitude/longitude coordinates
- 🚨 Weather Alerts: Retrieve active weather alerts for any US state
- 🔌 MCP Integration: Works seamlessly with Claude for Desktop and other MCP-compatible clients
- 📡 Real-time Data: Fetches live data from the National Weather Service API
Tools Available
get-forecast
Get weather forecast for a specific location.
Parameters:
latitude(float): Latitude of the location (-90 to 90)longitude(float): Longitude of the location (-180 to 180)
Example usage:
- "What's the weather forecast for San Francisco?" (Claude will use coordinates ~37.7749, -122.4194)
- "Give me the weather forecast for latitude 47.6062, longitude -122.3321" (Seattle)
get-alerts
Get active weather alerts for a US state.
Parameters:
state(string): Two-letter US state code (e.g., "CA", "NY", "TX")
Example usage:
- "What are the active weather alerts in California?"
- "Are there any weather warnings in Texas?"
Prerequisites
- Python 3.10 or higher
uvpackage manager- Access to the internet (for NWS API calls)
Installation
-
Install uv (if not already installed):
# macOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" -
Clone or navigate to the project directory:
cd weather -
Install dependencies:
uv sync
Running the Server
Standalone Testing
To test the server directly:
uv run weather.py
The server will start and listen on standard input/output. You can test it using the MCP inspector or other MCP clients.
With Claude for Desktop
-
Install Claude for Desktop from claude.ai/download
-
Configure Claude for Desktop by editing the configuration file:
macOS/Linux:
code ~/Library/Application\ Support/Claude/claude_desktop_config.jsonWindows:
code $env:AppData\Claude\claude_desktop_config.json -
Add the weather server configuration:
macOS/Linux:
{ "mcpServers": { "weather": { "command": "uv", "args": [ "--directory", "/ABSOLUTE/PATH/TO/YOUR/weather", "run", "weather.py" ] } } }Windows:
{ "mcpServers": { "weather": { "command": "uv", "args": [ "--directory", "C:\\ABSOLUTE\\PATH\\TO\\YOUR\\weather", "run", "weather.py" ] } } } -
Restart Claude for Desktop completely
-
Verify the integration by looking for the "Search and tools" icon in Claude for Desktop
Usage Examples
Once configured with Claude for Desktop, you can ask questions like:
- "What's the weather forecast for Sacramento?"
- "Give me the weather forecast for New York City"
- "What are the active weather alerts in Florida?"
- "Are there any severe weather warnings in Texas?"
- "What's the weather like at coordinates 40.7128, -74.0060?" (NYC)
API Details
This server uses the National Weather Service API (api.weather.gov), which:
- Provides free access to US weather data
- Requires no API key
- Returns data in JSON format
- Only covers US locations
Project Structure
weather/
├── main.py # Entry point (if needed)
├── weather.py # Main MCP server implementation
├── pyproject.toml # Project configuration and dependencies
├── uv.lock # Dependency lock file
└── README.md # This file
Troubleshooting
Server Not Showing Up in Claude
-
Check the configuration file syntax - Ensure valid JSON
-
Verify the absolute path - Use full paths, not relative ones
-
Check Claude's logs:
# macOS/Linux tail -f ~/Library/Logs/Claude/mcp*.log # Windows # Check logs in %AppData%\Claude\logs\ -
Restart Claude for Desktop completely
Tool Calls Failing
- Verify the server runs standalone:
uv run weather.py - Check for rate limiting - The NWS API has rate limits
- Ensure coordinates are for US locations - The NWS API only covers the US
- Check internet connectivity - Server needs to reach api.weather.gov
Common Error Messages
- "Failed to retrieve grid point data": Usually means coordinates are outside the US
- "No active alerts for this state": Not an error - just means no current alerts
- "Unable to fetch forecast data": Network issue or invalid coordinates
Development
Adding New Tools
To add new weather-related tools:
- Add the tool using the
@mcp.tool()decorator - Implement the async function with proper type hints
- Add error handling and validation
- Test with
uv run weather.py
Dependencies
Key dependencies (managed by uv):
mcp: Model Context Protocol SDKhttpx: HTTP client for API requestsfastmcp: Simplified MCP server framework
License
This project is part of the Model Context Protocol ecosystem. Check individual dependencies for their licenses.
Contributing
Feel free to submit issues and pull requests to improve the weather server functionality.