# 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
```bash
npm install
npm run build
```
## Usage
### Local Mode (Stdio Transport)
For local use with MCP clients like Claude Desktop:
```bash
# 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`):
```json
{
"mcpServers": {
"weather": {
"command": "node",
"args": ["/path/to/weather/build/index.js"]
}
}
}
```
### Remote Mode (HTTP/SSE Transport)
For remote access via HTTP:
```bash
# 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
```bash
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
```bash
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
```bash
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:
```bash
curl -N http://localhost:3000/mcp \
-H "Accept: text/event-stream" \
-H "mcp-session-id: YOUR_SESSION_ID"
```
### 5. Terminate Session
```bash
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
```bash
TRANSPORT=http PORT=3000 node build/index.js
```
### Production (with PM2)
```bash
pm2 start build/index.js --name weather-mcp -- TRANSPORT=http PORT=3000
```
### Docker
```dockerfile
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
