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

Clone the repository:

git clone <repository-url>
cd weather-mcp-server

Install dependencies:

npm install

Build the project:

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.

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:

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.

npm run proxy      # Runs on port 3002

Test it:

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.

npm run dev        # Development
npm start          # Production

See INTEGRATION.md for integrating with your Next.js app.

📖 For detailed information about improvements and architecture, see IMPROVEMENTS.md

Running the MCP Server Directly

Development mode (with hot reload):

npm run dev

Production mode:

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

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

Or use the development version:

{
  "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:

# Terminal 1: Start the proxy
npm run proxy

# Terminal 2: Run tests
npm test

Option 2: MCP Inspector (Interactive UI)

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

Edit src/index.ts to modify or add tools
Run npm run build to compile
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:

{
  "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:

{
  "city": "New York",
  "country": "US",
  "days": 5
}

Tool: get_weather_alerts

Parameters:

city (required): City name
country (optional): Country code

Example:

{
  "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:

{
  "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:

{
  "city": "London",
  "month": 7,
  "years_back": 5
}

Data Source

This server uses the Open-Meteo API, 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:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Test thoroughly with npm run test:inspector
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

Weather MCP Server

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

Clone the repository:

git clone <repository-url>
cd weather-mcp-server

Install dependencies:

npm install

Build the project:

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.

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:

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.

npm run proxy      # Runs on port 3002

Test it:

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.

npm run dev        # Development
npm start          # Production

See INTEGRATION.md for integrating with your Next.js app.

📖 For detailed information about improvements and architecture, see IMPROVEMENTS.md

Running the MCP Server Directly

Development mode (with hot reload):

npm run dev

Production mode:

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

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

Or use the development version:

{
  "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:

# Terminal 1: Start the proxy
npm run proxy

# Terminal 2: Run tests
npm test

Option 2: MCP Inspector (Interactive UI)

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

Edit src/index.ts to modify or add tools
Run npm run build to compile
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:

{
  "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:

{
  "city": "New York",
  "country": "US",
  "days": 5
}

Tool: get_weather_alerts

Parameters:

city (required): City name
country (optional): Country code

Example:

{
  "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:

{
  "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:

{
  "city": "London",
  "month": 7,
  "years_back": 5
}

Data Source

This server uses the Open-Meteo API, 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:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Test thoroughly with npm run test:inspector
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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