Weather-MCP-Server

shayrylmae/Weather-MCP-Server

3.2

If you are the rightful owner of Weather-MCP-Server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Weather MCP Server provides real-time and historical weather data using the Open-Meteo API, enabling AI assistants and applications to access comprehensive weather information through a standardized interface.

Tools
5
Resources
0
Prompts
0

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
  1. Install dependencies:
npm install
  1. 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 for integrating with your Next.js app.

📖 For detailed information about improvements and architecture, see

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