Skip to Content
mcpWeather MCP

Weather MCP

Weather MCP on GitHub 

Introduction

The Weather MCP (Model Context Protocol) server provides weather-related tools that allow you to retrieve weather forecasts and alerts for locations in the United States. It integrates with the National Weather Service (NWS) API to deliver accurate and up-to-date weather information.

The Weather MCP server exposes two main tools:

  • get_forecast: Retrieves detailed weather forecasts for a specific location using latitude and longitude coordinates
  • get_alerts: Retrieves active weather alerts for a given US state

Usage

The Weather MCP server runs as a stdio-based MCP server. To use it, you need to configure it in your MCP client application (such as Claude Desktop or other MCP-compatible clients).

Installation

The Weather MCP is available as part of the @ai-kits/mcp package. The server can be executed via the weather binary command.

Configuration

To configure the Weather MCP server in your MCP client, add the following configuration:

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["-y", "@ai-kits/mcp", "weather"]
    }
  }
}

Or if you have the package installed locally:

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["path/to/@ai-kits/mcp/dist/mcps/weather/index.js"]
    }
  }
}

Note: The Weather MCP uses the National Weather Service API, which only supports locations within the United States. Forecast requests for locations outside the US will return an error.

API Reference

Tool: get_forecast

Retrieves a detailed weather forecast for a specific location using geographic coordinates.

Parameters

ParameterTypeRequiredDescription
latitudenumberYesThe latitude of the location. Must be a number between -90 and 90 (inclusive).
longitudenumberYesThe longitude of the location. Must be a number between -180 and 180 (inclusive).

Parameter Details

  • latitude (number, required)

    • Range: -90 to 90
    • Description: The geographic latitude coordinate of the location for which you want to retrieve the weather forecast. Positive values represent locations north of the equator, negative values represent locations south of the equator.
    • Example: 40.7128 (New York City)

  • longitude (number, required)

    • Range: -180 to 180
    • Description: The geographic longitude coordinate of the location for which you want to retrieve the weather forecast. Positive values represent locations east of the Prime Meridian, negative values represent locations west of the Prime Meridian.
    • Example: -74.0060 (New York City)

Return Value

The tool returns a text response containing formatted forecast information. The response includes:

  • Location coordinates
  • Multiple forecast periods, each containing:
    • Period name (e.g., “Tonight”, “Tomorrow”, “Monday”)
    • Temperature (with unit, typically Fahrenheit)
    • Wind speed and direction
    • Short forecast description

Tool: get_alerts

Retrieves active weather alerts for a given US state.

Parameters

ParameterTypeRequiredDescription
statestringYesThe 2-letter US state code. Must be exactly 2 characters long.

Parameter Details

  • state (string, required)
    • Length: Exactly 2 characters
    • Description: The two-letter US state abbreviation code (case-insensitive). The tool will automatically convert the input to uppercase.
    • Examples: "NY" (New York), "CA" (California), "TX" (Texas), "FL" (Florida)

Return Value

The tool returns a text response containing formatted alert information. Each alert includes:

  • Event type
  • Area description
  • Severity level
  • Status
  • Headline

If no alerts are active for the specified state, the tool returns a message indicating no alerts were found.

Output Examples

Example 1: Forecast Response

Forecast for 40.7128, -74.006:

Tonight:
Temperature: 45°F
Wind: 5 mph NW
Partly cloudy
---
Tomorrow:
Temperature: 62°F
Wind: 10 mph SW
Sunny
---
Monday:
Temperature: 58°F
Wind: 8 mph NE
Partly sunny
---
...

Example 2: Alerts Response

Active alerts for NY:

Event: Severe Thunderstorm Warning
Area: New York County, NY
Severity: Severe
Status: Actual
Headline: Severe Thunderstorm Warning issued June 15 at 3:00PM EDT
--------------------------------
Event: Flash Flood Watch
Area: Kings County, NY
Severity: Moderate
Status: Actual
Headline: Flash Flood Watch issued June 15 at 2:30PM EDT
--------------------------------

Example 3: No Alerts Response

No weather alerts found

Usage Examples

Example 1: Get Forecast for New York City

// Tool call
{
  "name": "get_forecast",
  "arguments": {
    "latitude": 40.7128,
    "longitude": -74.0060
  }
}

Expected Output: A detailed forecast for New York City including multiple periods with temperature, wind, and conditions.

Example 2: Get Forecast for Los Angeles

// Tool call
{
  "name": "get_forecast",
  "arguments": {
    "latitude": 34.0522,
    "longitude": -118.2437
  }
}

Expected Output: A detailed forecast for Los Angeles with weather conditions for upcoming periods.

Example 3: Get Weather Alerts for California

// Tool call
{
  "name": "get_alerts",
  "arguments": {
    "state": "CA"
  }
}

Expected Output: A list of active weather alerts for California, including warnings, watches, and advisories.

Example 4: Get Weather Alerts for Texas

// Tool call
{
  "name": "get_alerts",
  "arguments": {
    "state": "tx"  // Case-insensitive
  }
}

Expected Output: Active weather alerts for Texas, formatted with event type, area, severity, status, and headline.

Example 5: Error Handling - Invalid Coordinates

If you request a forecast for coordinates outside the US:

// Tool call
{
  "name": "get_forecast",
  "arguments": {
    "latitude": 51.5074,
    "longitude": -0.1278  // London, UK
  }
}

Expected Output:

Failed to retrieve grid point data for coordinates: 51.5074, -0.1278. This location may not be supported by the NWS API (only US locations are supported).

Technical Details

  • API Base URL: https://api.weather.gov
  • User Agent: weather-app/1.0
  • Transport: stdio (Standard Input/Output)
  • Server Name: weather
  • Server Version: 1.0.0
  • Data Format: The server uses the NWS GeoJSON API format and returns formatted text responses

Limitations

  1. Geographic Coverage: The Weather MCP only supports locations within the United States. Forecast requests for international locations will fail.

  2. State Alerts: The get_alerts tool requires a valid 2-letter US state code. Invalid state codes may return empty results or errors.

  3. API Dependency: The server depends on the National Weather Service API availability. Network issues or API downtime may affect functionality.

  4. Data Format: All responses are returned as plain text. The server formats the data for readability but does not return structured JSON responses.

Last updated on
ReAct System Prompt