🌤️ Kaushik's Weather MCP Server

A production-ready Model Context Protocol (MCP) server built in TypeScript, connecting LLMs (such as Claude Desktop, Cursor, and custom AI agents) to real-time National Weather Service (NWS / NOAA) meteorological data.

🔗 Live Proof of Integration

🚀 Verified Working with Claude Desktop: Check out the live chat session demonstrating real-time forecast retrieval, alerts, and health diagnostics:
👉 View Live Claude AI Chat Proof

Related MCP server: mcp-weather

✨ Architectural Highlights

• 🏗️ Modular Clean Architecture: Decoupled into dedicated service layers (CacheService, RateLimiterService, NwsClient, Logger, Formatter).

• 📡 Official Meteorological Bulletins: Structured weather reports with standardized metadata and provider attribution.

• ⚡ In-Memory Caching (5-Min TTL): Thread-safe in-memory cache reducing upstream API traffic by up to 80%.

• 🛡️ Zero-Vibe Security Layer: Strict input sanitization, XSS entity escaping, and client-isolated rate limiting (100 req/min).

• 🔁 Resilience & Fault Tolerance: Automated exponential backoff retries for HTTP 5xx / 429 errors and request timeout guards.

• 🩺 Observability & Diagnostics: Built-in health_check, get_metrics, and clear_cache tools with structured JSON logging.

📁 Project Structure

weather/
├── src/
│   ├── config/          # Central configuration & runtime constants
│   ├── services/        # Core business logic (Cache, RateLimiter, NwsClient, Formatter, Logger)
│   ├── tools/           # MCP Tool handlers (alerts, forecast, diagnostics)
│   ├── types/           # Strongly typed TypeScript interfaces
│   ├── utils/           # Input sanitization and security helpers
│   └── index.ts         # Server bootstrap, transport initialization & graceful shutdown
├── tests/
│   ├── unit/            # Unit test suites (utils, sanitizer, cache)
│   ├── integration/     # Upstream NWS API integration & retry tests
│   ├── performance/     # Cache throughput & rate-limiting load tests
│   ├── security/        # XSS, injection prevention & boundary tests
│   └── basic.test.ts    # Comprehensive test runner
├── build/               # Compiled ES module JavaScript distribution
├── package.json
└── tsconfig.json

🛠️ MCP Tools

🚀 Getting Started

1. Clone & Install

git clone https://github.com/Kaushik2105/mcp-weather.git
cd mcp-weather
npm install

2. Build

npm run build

3. Run Test Suite

npm test

🔌 Connecting to Claude Desktop

Add this configuration to your Claude Desktop configuration file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "kaushik-weather": {
      "command": "node",
      "args": [
        "c:/Workholic/LawSikho/POCs/weather/weather/build/index.js"
      ]
    }
  }
}

Note: Restart Claude Desktop after saving the configuration.

💬 Sample Prompts for Claude

• "Show me the official forecast bulletin from Kaushik's weather tool for Los Angeles (Lat: 34.0522, Lon: -118.2437)"

• "Are there any active weather alerts for Florida (FL)?"

• "Run a health check diagnostic on Kaushik's weather MCP server."

👨‍💻 Author

Kaushik Karmakar

• GitHub: @Kaushik2105

• Live Integration Proof: Claude AI Chat