# MCP Weather Server

A Model Context Protocol (MCP) server that provides weather-related functionality for any MCP client. This server integrates with the National Weather Service (NWS) API to deliver real-time weather alerts and forecasts for US locations.

![MCP Weather Server Interface](capture.png)

## Features

### 🌤️ Weather Alerts

- Get active weather alerts for any US state using two-letter state codes
- Displays event type, affected area, severity, status, and headlines
- Real-time data from the National Weather Service

### 📍 Weather Forecasts

- Get detailed weather forecasts for any US location using coordinates
- Includes temperature, wind conditions, and short forecast descriptions
- Supports multiple forecast periods (daily/hourly)

## Prerequisites

- Node.js (version 14 or higher)
- pnpm (Package Manager) - automatically managed via Corepack
- Any MCP client (Claude Desktop, Ollama, etc.)

## Installation

1. Install dependencies:

```bash
pnpm install
```

2. Build the project:

```bash
pnpm run build
```

## Configuration

To integrate this server with an MCP client, you need to configure your client's MCP server settings. Here are examples for popular clients:

### Claude Desktop

1. Open your Claude Desktop configuration file:

```bash
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

2. Add the following configuration to your MCP servers section:

```json
{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/ABSOLUTE_PATH/mcp-server-weather/build/index.js"]
    }
  }
}
```

### Other MCP Clients

For other MCP clients, add a server configuration with:

- **Command**: `node`
- **Args**: `["/ABSOLUTE_PATH/mcp-server-weather/build/index.js"]`

Replace `/ABSOLUTE_PATH` with the actual absolute path to your project directory.

## Usage

Once configured, you can use the weather server through any MCP client with these commands:

### Get Weather Alerts

```
Get weather alerts for California
```

- Returns active weather alerts for the specified state
- Uses two-letter state codes (CA, NY, TX, etc.)

### Get Weather Forecast

```
Get the weather forecast for coordinates 40.7128, -74.0060
```

- Returns detailed forecast for the specified coordinates
- Only works for US locations (NWS API limitation)
- Includes temperature, wind, and forecast descriptions

## Development

The project is written in TypeScript and uses the following key dependencies:

- `@modelcontextprotocol/sdk`: For MCP server implementation
- `zod`: For runtime type validation and schema definition
- `typescript`: For type safety and development

### Project Structure

```
├── src/
│   └── index.ts      # Main server entry point with all weather tools
├── build/           # Compiled JavaScript output
├── package.json     # Project dependencies and scripts
└── pnpm-lock.yaml   # pnpm lock file for dependency management
```

### Available Scripts

- `pnpm install` - Install dependencies
- `pnpm run build` - Compile TypeScript to JavaScript
- `pnpm run clean` - Remove build directory

## API Integration

This server integrates with the National Weather Service (NWS) API:

- **Base URL**: `https://api.weather.gov`
- **Data Format**: GeoJSON
- **Coverage**: United States only
- **Rate Limits**: Standard NWS API limits apply

### Supported Endpoints

- `/alerts?area={STATE}` - Get weather alerts by state
- `/points/{lat},{lon}` - Get grid point data for coordinates
- `/gridpoints/{office}/{gridX},{gridY}/forecast` - Get forecast data

## Monitoring and Debugging

### Logs

MCP clients typically write logs to their respective directories:

**Claude Desktop:**

- `~/Library/Logs/Claude/mcp*.log`

**Other clients:**

- Refer to your specific client's documentation for log locations

To monitor logs in real-time (Claude Desktop example):

```bash
# View recent logs and follow new entries
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
```

### Error Handling

The server includes comprehensive error handling for:

- Network request failures
- Invalid coordinates or state codes
- NWS API service unavailability
- Data parsing errors

## Limitations

- **Geographic Coverage**: Only supports US locations (NWS API limitation)
- **Coordinate Precision**: Uses 4 decimal places for coordinate precision
- **Data Source**: Relies on National Weather Service API availability

## Resources

- [MCP Server Quickstart Guide](https://modelcontextprotocol.io/quickstart/server)
- [Model Context Protocol Documentation](https://modelcontextprotocol.io)
- [National Weather Service API](https://www.weather.gov/documentation/services-web-api)

## License

ISC License - See LICENSE file for details