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

Related MCP server: Weather MCP Server

Installation

Prerequisites

• Node.js 16 or higher

• npm or yarn

Setup

1. Clone the repository:

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

2. Install dependencies:

npm install

3. 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

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:

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

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