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:

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