MCP Weather

A Model Context Protocol (MCP) implementation for weather data with natural language processing capabilities, consisting of a server, API client, and web interface.

Project Structure

This is a monorepo containing three packages:

• packages/mcp-server/ - MCP server implementation for weather data using National Weather Service API
• packages/mcp-client/ - REST API bridge with natural language processing using Google Gemini AI
• packages/web-client/ - React TypeScript web interface for user interactions

Features

• 🌤️ Current Weather Forecasts - Get weather forecasts for any US location
• ⚠️ Weather Alerts - Retrieve active weather alerts by state
• 🤖 Natural Language Processing - Ask questions in plain English
• 🌐 Web Interface - User-friendly React application
• 🔌 MCP Protocol - Compatible with MCP-enabled applications

Requirements

• Node.js 18+
• Google Gemini API key (for natural language processing)

Quick Start

1. Install dependencies:

   npm install

2. Set up environment variables: Create a .env file in the root directory:

   GEMINI_API_KEY=your_google_gemini_api_key
   PORT=3001

3. Build all packages:

   npm run build

4. Start the system:

   # Terminal 1: Start the MCP client API
   npm start
   
   # Terminal 2: Start the web interface
   npm run dev:web

5. Access the application:

   • Web interface: http://localhost:3000
   • API endpoint: http://localhost:3001

Usage Examples

Web Interface

Open http://localhost:3000 and try these queries:

• "What's the weather forecast for San Francisco?"
• "Are there any weather alerts in California?"
• "Weather forecast for New York City"
• "Alerts in Texas"

API Endpoints

# Get weather forecast
curl -X POST http://localhost:3001/api/weather/query \
  -H "Content-Type: application/json" \
  -d '{"query": "Weather in Miami"}'

# Get weather alerts
curl -X POST http://localhost:3001/api/weather/query \
  -H "Content-Type: application/json" \
  -d '{"query": "Alerts in Florida"}'

Development

Individual Package Commands

# Build specific packages
npm run build:server
npm run build:client
npm run build:web

# Start web development server
npm run dev:web

Architecture

1. MCP Server (mcp-server) - Provides weather tools via MCP protocol
2. MCP Client (mcp-client) - REST API that bridges natural language to MCP tools
3. Web Client (web-client) - React interface for end users

Data Limitations

• Current data only - No historical weather data
• US locations only - Uses National Weather Service API
• Forecast range - Next few days only
• No climate statistics - No averages or long-term trends

Environment Variables

Create a .env file in the root directory:

# Required for natural language processing
GEMINI_API_KEY=your_google_gemini_api_key

# Optional - API server port (default: 3001)
PORT=3001

License

ISC