Weather MCP Server - Usage Guide

A Model Context Protocol (MCP) server that provides weather information using the National Weather Service API. Supports both local (stdio) and remote (HTTP/SSE) access.

Features

Dual Transport Support: Run locally via stdio or remotely via HTTP/SSE
Weather Alerts: Get active weather alerts by state
Weather Forecasts: Get detailed forecasts by coordinates (US locations only)
Session Management: Automatic session handling for remote connections

Installation

npm install
npm run build

Usage

Local Mode (Stdio Transport)

For local use with MCP clients like Claude Desktop:

# Default mode - no environment variable needed
node build/index.js

# Or explicitly set stdio mode
TRANSPORT=stdio node build/index.js

Configuration for Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/path/to/weather/build/index.js"]
    }
  }
}

Remote Mode (HTTP/SSE Transport)

For remote access via HTTP:

# Start HTTP server on default port 3000
TRANSPORT=http node build/index.js

# Or specify a custom port
TRANSPORT=http PORT=8080 node build/index.js

The server will start on http://localhost:3000/mcp (or your specified port).

Remote Access Examples

1. Initialize Session

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "my-client",
        "version": "1.0.0"
      }
    }
  }'

Response: Returns session ID in mcp-session-id header. Save this for subsequent requests.

2. Get Weather Forecast

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_forecast",
      "arguments": {
        "latitude": 37.7749,
        "longitude": -122.4194
      }
    }
  }'

3. Get Weather Alerts

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_alerts",
      "arguments": {
        "state": "CA"
      }
    }
  }'

4. Open SSE Stream (Optional)

For receiving server-initiated messages:

curl -N http://localhost:3000/mcp \
  -H "Accept: text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID"

5. Terminate Session

curl -X DELETE http://localhost:3000/mcp \
  -H "mcp-session-id: YOUR_SESSION_ID"

Available Tools

`get_forecast`

Get weather forecast for a location.

Parameters:

latitude (number): Latitude of the location (-90 to 90)
longitude (number): Longitude of the location (-180 to 180)

Note: Only US locations are supported by the National Weather Service API.

`get_alerts`

Get active weather alerts for a US state.

Parameters:

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

Environment Variables

Variable	Description	Default	Example
`TRANSPORT`	Transport mode: `stdio` or `http`	`stdio`	`http`
`PORT`	HTTP server port (HTTP mode only)	`3000`	`8080`

Architecture

Stdio Mode

Single server instance
Communicates via stdin/stdout
Ideal for local MCP clients

HTTP Mode

Express-based HTTP server
Session-based architecture
Multiple concurrent sessions supported
Automatic session cleanup on disconnect
SSE streaming for real-time updates

Deployment

Local Development

TRANSPORT=http PORT=3000 node build/index.js

Production (with PM2)

pm2 start build/index.js --name weather-mcp -- TRANSPORT=http PORT=3000

Docker

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY build ./build
ENV TRANSPORT=http
ENV PORT=3000
EXPOSE 3000
CMD ["node", "build/index.js"]

Troubleshooting

"Failed to retrieve grid point data"

Ensure coordinates are within the United States
NWS API only supports US locations

"Invalid or missing session ID"

Initialize a session first using the initialize method
Include the mcp-session-id header in all subsequent requests

Server not starting in HTTP mode

Check if port is already in use
Verify TRANSPORT=http environment variable is set

License

ISC

Weather MCP Server - Usage Guide

A Model Context Protocol (MCP) server that provides weather information using the National Weather Service API. Supports both local (stdio) and remote (HTTP/SSE) access.

Features

Dual Transport Support: Run locally via stdio or remotely via HTTP/SSE
Weather Alerts: Get active weather alerts by state
Weather Forecasts: Get detailed forecasts by coordinates (US locations only)
Session Management: Automatic session handling for remote connections

Installation

npm install
npm run build

Usage

Local Mode (Stdio Transport)

For local use with MCP clients like Claude Desktop:

# Default mode - no environment variable needed
node build/index.js

# Or explicitly set stdio mode
TRANSPORT=stdio node build/index.js

Configuration for Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/path/to/weather/build/index.js"]
    }
  }
}

Remote Mode (HTTP/SSE Transport)

For remote access via HTTP:

# Start HTTP server on default port 3000
TRANSPORT=http node build/index.js

# Or specify a custom port
TRANSPORT=http PORT=8080 node build/index.js

The server will start on http://localhost:3000/mcp (or your specified port).

Remote Access Examples

1. Initialize Session

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "my-client",
        "version": "1.0.0"
      }
    }
  }'

Response: Returns session ID in mcp-session-id header. Save this for subsequent requests.

2. Get Weather Forecast

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_forecast",
      "arguments": {
        "latitude": 37.7749,
        "longitude": -122.4194
      }
    }
  }'

3. Get Weather Alerts

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_alerts",
      "arguments": {
        "state": "CA"
      }
    }
  }'

4. Open SSE Stream (Optional)

For receiving server-initiated messages:

curl -N http://localhost:3000/mcp \
  -H "Accept: text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID"

5. Terminate Session

curl -X DELETE http://localhost:3000/mcp \
  -H "mcp-session-id: YOUR_SESSION_ID"

Available Tools

`get_forecast`

Get weather forecast for a location.

Parameters:

latitude (number): Latitude of the location (-90 to 90)
longitude (number): Longitude of the location (-180 to 180)

Note: Only US locations are supported by the National Weather Service API.

`get_alerts`

Get active weather alerts for a US state.

Parameters:

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

Environment Variables

Variable	Description	Default	Example
`TRANSPORT`	Transport mode: `stdio` or `http`	`stdio`	`http`
`PORT`	HTTP server port (HTTP mode only)	`3000`	`8080`

Architecture

Stdio Mode

Single server instance
Communicates via stdin/stdout
Ideal for local MCP clients

HTTP Mode

Express-based HTTP server
Session-based architecture
Multiple concurrent sessions supported
Automatic session cleanup on disconnect
SSE streaming for real-time updates

Deployment

Local Development

TRANSPORT=http PORT=3000 node build/index.js

Production (with PM2)

pm2 start build/index.js --name weather-mcp -- TRANSPORT=http PORT=3000

Docker

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY build ./build
ENV TRANSPORT=http
ENV PORT=3000
EXPOSE 3000
CMD ["node", "build/index.js"]

Troubleshooting

"Failed to retrieve grid point data"

Ensure coordinates are within the United States
NWS API only supports US locations

"Invalid or missing session ID"

Initialize a session first using the initialize method
Include the mcp-session-id header in all subsequent requests

Server not starting in HTTP mode

Check if port is already in use
Verify TRANSPORT=http environment variable is set

License

ISC