MCP Weather Server MCP Server

MCP WEATHER SERVER WRITTEN IN TYPESCRIPT

Protocol Map

This weather MCP server implements the Model Context Protocol (MCP) to provide weather data through a standardized interface. Below is the complete protocol mapping showing how the server communicates with MCP clients.

Server Information

• Name: weather
• Version: 1.0.0
• Transport: STDIO (Standard Input/Output)
• Protocol: Model Context Protocol

Capabilities

{
  "capabilities": {
    "tools": {
      "listChanged": true
    }
  }
}

Tools

The server exposes two tools for weather data retrieval:

1. `get_alerts`

Retrieves active weather alerts for a US state.

Input Schema:

{
  "type": "object",
  "properties": {
    "state": {
      "type": "string",
      "description": "Two-letter US state code (e.g. CA, NY)",
      "minLength": 2,
      "maxLength": 2
    }
  },
  "required": ["state"]
}

Example Request:

{
  "method": "tools/call",
  "params": {
    "name": "get_alerts",
    "arguments": {
      "state": "CA"
    }
  }
}

Example Response:

{
  "content": [
    {
      "type": "text",
      "text": "Event: Heat Advisory\nArea: Los Angeles County\nSeverity: Moderate\nDescription: Dangerously hot conditions...\nInstructions: Drink plenty of fluids..."
    }
  ]
}

Error Response:

{
  "content": [
    {
      "type": "text",
      "text": "Unable to fetch alerts or no alerts found."
    }
  ]
}

2. `get_forecast`

Retrieves weather forecast for a specific location using latitude and longitude coordinates.

Input Schema:

{
  "type": "object",
  "properties": {
    "latitude": {
      "type": "number",
      "description": "Latitude of the location",
      "minimum": -90,
      "maximum": 90
    },
    "longitude": {
      "type": "number",
      "description": "Longitude of the location",
      "minimum": -180,
      "maximum": 180
    }
  },
  "required": ["latitude", "longitude"]
}

Example Request:

{
  "method": "tools/call",
  "params": {
    "name": "get_forecast",
    "arguments": {
      "latitude": 38.5816,
      "longitude": -121.4944
    }
  }
}

Example Response:

{
  "content": [
    {
      "type": "text",
      "text": "Tonight:\nTemperature: 65°F\nWind: 5 mph SW\nForecast: Partly cloudy with a slight chance of showers.\n---\nTomorrow:\nTemperature: 78°F\nWind: 10 mph W\nForecast: Sunny skies throughout the day."
    }
  ]
}

Error Responses:

{
  "content": [
    {
      "type": "text",
      "text": "Failed to retrieve grid point data for coordinates: 38.5816, -121.4944. This location may not be supported by the NWS API (only US locations are supported)."
    }
  ]
}

Communication Flow

sequenceDiagram
    participant Client as MCP Client (Claude)
    participant Server as Weather Server
    participant NWS as National Weather Service API

    Client->>Server: Initialize Connection (STDIO)
    Server->>Client: Server Info + Capabilities
    
    Client->>Server: List Tools
    Server->>Client: [get_alerts, get_forecast]
    
    Client->>Server: Call Tool: get_forecast(lat, lon)
    Server->>NWS: GET /points/{lat},{lon}
    NWS->>Server: Grid Point Data
    Server->>NWS: GET {forecast_url}
    NWS->>Server: Forecast Data
    Server->>Client: Formatted Forecast Text
    
    Client->>Server: Call Tool: get_alerts(state)
    Server->>NWS: GET /alerts/active/area/{state}
    NWS->>Server: Active Alerts
    Server->>Client: Formatted Alerts Text

Protocol Messages

Initialization

Client → Server:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "Claude Desktop",
      "version": "1.0.0"
    }
  }
}

Server → Client:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "weather",
      "version": "1.0.0"
    }
  }
}

Tool Discovery

Client → Server:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Server → Client:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "get_alerts",
        "description": "Get weather alerts for a US state.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "state": {
              "type": "string",
              "description": "Two-letter US state code (e.g. CA, NY)"
            }
          },
          "required": ["state"]
        }
      },
      {
        "name": "get_forecast",
        "description": "Get weather forecast for a location.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "latitude": {