# Weather MCP Server

A Model Context Protocol (MCP) server that provides real-time and historical weather data using the Open-Meteo API. This server enables AI assistants and applications to access comprehensive weather information through a standardized interface.

## Features

This MCP server provides 5 powerful weather tools:

### 1. **get_current_weather**
Get real-time current weather conditions for any city worldwide.
- Temperature (actual and feels-like)
- Humidity
- Precipitation
- Weather description
- Wind speed and direction

### 2. **get_weather_forecast**
Retrieve weather forecasts for up to 16 days ahead.
- Daily max/min temperatures
- Precipitation predictions
- Weather conditions
- Wind speeds
- Perfect for trip planning and event scheduling

### 3. **get_weather_alerts**
Check for weather warnings and alerts based on current conditions.
- Extreme temperature warnings
- High wind alerts
- Heavy precipitation notices
- Thunderstorm warnings
- Real-time condition-based alerts

### 4. **get_growing_conditions**
Access agricultural and gardening data.
- Growing Degree Days (GDD) calculation
- Solar radiation levels
- Soil temperature and moisture
- Humidity metrics
- Customizable base temperature for different crops

### 5. **get_historical_weather**
Retrieve historical weather data for specific months.
- Monthly statistics over multiple years (up to 10 years back)
- Average, max, and min temperatures
- Total precipitation
- Average wind speed
- Climate trend analysis

## Installation

### Prerequisites
- Node.js 16 or higher
- npm or yarn

### Setup

1. Clone the repository:
```bash
git clone <repository-url>
cd weather-mcp-server
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build
```

## Usage

### Deployment Options

This server supports multiple transport modes:

#### 1. **SSE Transport** (Recommended for HTTP) ⭐

Server-Sent Events transport provides a persistent, stateful connection over HTTP.

```bash
npm run dev:sse    # Development (port 3003)
npm run start:sse  # Production (port 3003)
```

**Benefits:**
- ✅ Persistent connection maintains state across tool calls
- ✅ Native MCP protocol support over HTTP
- ✅ Better efficiency for streaming AI interactions
- ✅ Standards-compliant SSE implementation

**Test it:**
```bash
curl http://localhost:3003/health
curl http://localhost:3003/
```

#### 2. **HTTP Proxy** (Simple REST API)

Request-response HTTP wrapper for quick testing and REST API usage.

```bash
npm run proxy      # Runs on port 3002
```

**Test it:**
```bash
npm test
curl "http://localhost:3002/weather/current?city=Manila&country=PH"
```

#### 3. **Stdio Transport** (Original)

Standard MCP over stdio for Claude Desktop and MCP Inspector.

```bash
npm run dev        # Development
npm start          # Production
```

See **[INTEGRATION.md](./INTEGRATION.md)** for integrating with your Next.js app.

> 📖 **For detailed information about improvements and architecture**, see **[IMPROVEMENTS.md](./IMPROVEMENTS.md)**

### Running the MCP Server Directly

**Development mode** (with hot reload):
```bash
npm run dev
```

**Production mode**:
```bash
npm start
```

### Configuration with Claude Desktop

Add this server to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/absolute/path/to/weather-mcp-server/dist/index.js"]
    }
  }
}
```

Or use the development version:
```json
{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["-y", "tsx", "/absolute/path/to/weather-mcp-server/src/index.ts"]
    }
  }
}
```

### Configuration with Other MCP Clients

This server uses the standard MCP protocol over stdio, so it can be integrated with any MCP-compatible client. Refer to your client's documentation for specific configuration instructions.

## Development

### Project Structure

```
weather-mcp-server/
├── src/
│   ├── index.ts                   # Main MCP server (stdio transport)
│   ├── sse-server.ts             # SSE transport server with routing (modified)
│   ├── sse-server-fixed.ts       # SSE server variant (untracked)
│   └── sse-server-with-routing.ts # SSE server variant (untracked)
├── dist/
│   ├── index.js                   # Compiled stdio server
│   └── sse-server.js             # Compiled SSE server
├── http-proxy.js                  # HTTP proxy wrapper (11KB)
├── test-integration.js            # Integration test suite
├── test-sse.html                  # SSE transport test page
├── package.json                   # Dependencies and scripts
├── tsconfig.json                  # TypeScript configuration
├── CLAUDE.md                      # Claude Code instructions
├── INTEGRATION.md                 # Integration guide for Next.js
├── IMPROVEMENTS.md                # Detailed improvements documentation
├── CHANGELOG.md                   # Version history and changes
└── README.md                      # This file
```

### Available Scripts

- `npm run build` - Compile TypeScript to JavaScript
- `npm run dev` - Run stdio transport in development mode
- `npm run dev:sse` - Run SSE transport in development mode (port 3003) ⭐
- `npm start` - Run the compiled stdio transport
- `npm run start:sse` - Run the compiled SSE transport (port 3003) ⭐
- `npm run proxy` - Build and start HTTP proxy server (port 3002)
- `npm test` - Run integration tests (requires proxy to be running)
- `npm run test:inspector` - Test with MCP Inspector (interactive UI)
- `npm run test:manual` - Run manual tests

### Testing

**Option 1: Integration Tests** (Recommended)

Start the HTTP proxy and run automated tests:
```bash
# Terminal 1: Start the proxy
npm run proxy

# Terminal 2: Run tests
npm test
```

**Option 2: MCP Inspector** (Interactive UI)

```bash
npm run test:inspector
```

This will open a web interface where you can:
- View all available tools
- Test each tool with different inputs
- See responses in real-time
- Debug any issues

### Making Changes

1. Edit `src/index.ts` to modify or add tools
2. Run `npm run build` to compile
3. Test using one of these methods:
   - `npm run proxy` then `npm test` for automated tests
   - `npm run test:inspector` for interactive testing
   - Restart your MCP client (e.g., Claude Desktop)

## API Reference

### Tool: get_current_weather

**Parameters:**
- `city` (required): City name (e.g., "London", "Tokyo")
- `country` (optional): Country code (e.g., "US", "GB", "JP")

**Example:**
```json
{
  "city": "Paris",
  "country": "FR"
}
```

### Tool: get_weather_forecast

**Parameters:**
- `city` (required): City name
- `country` (optional): Country code
- `days` (optional): Number of forecast days (1-16, default: 7)

**Example:**
```json
{
  "city": "New York",
  "country": "US",
  "days": 5
}
```

### Tool: get_weather_alerts

**Parameters:**
- `city` (required): City name
- `country` (optional): Country code

**Example:**
```json
{
  "city": "Miami",
  "country": "US"
}
```

### Tool: get_growing_conditions

**Parameters:**
- `city` (required): City name
- `country` (optional): Country code
- `base_temp` (optional): Base temperature for GDD calculation in °C (default: 10)

**Example:**
```json
{
  "city": "Sacramento",
  "country": "US",
  "base_temp": 10
}
```

### Tool: get_historical_weather

**Parameters:**
- `city` (required): City name
- `month` (required): Month number (1-12, where 1=January, 12=December)
- `country` (optional): Country code
- `years_back` (optional): Number of years back to retrieve (1-10, default: 1)

**Example:**
```json
{
  "city": "London",
  "month": 7,
  "years_back": 5
}
```

## Data Source

This server uses the [Open-Meteo API](https://open-meteo.com/), which provides:
- Free access with no API key required
- High-quality weather data from multiple sources
- Historical weather archives
- Global coverage
- No rate limiting for reasonable use

## Technical Details

- **Protocol**: Model Context Protocol (MCP)
- **Transport Modes**:
  - Stdio (standard MCP)
  - Server-Sent Events (SSE) with message routing
  - HTTP Proxy (REST API wrapper)
- **Language**: TypeScript with Node.js
- **Runtime**: Node.js 16+
- **Dependencies**:
  - `@modelcontextprotocol/sdk` (^1.18.2) - MCP framework
  - `zod` (^3.25.76) - Runtime type validation
- **Dev Dependencies**:
  - `tsx` (^4.20.6) - TypeScript execution
  - `typescript` (^5.9.3) - TypeScript compiler
  - `@types/node` (^24.6.1) - Node.js type definitions
- **APIs Used**:
  - Open-Meteo Forecast API
  - Open-Meteo Geocoding API
  - Open-Meteo Archive API (for historical data)

## Contributing

Contributions are welcome! To contribute:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Test thoroughly with `npm run test:inspector`
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

## License

ISC License

## Support

For issues, questions, or contributions, please open an issue on the repository.

---

Built with the [Model Context Protocol](https://modelcontextprotocol.io/)