🌤️ Weather MCP Server

A Model Context Protocol (MCP) server that provides weather data and alerts using the National Weather Service API.

📋 Description

This MCP server provides weather forecast and alert data for US locations through the National Weather Service API. It offers two main tools:

• Weather Alerts: Get active weather alerts for any US state

• Weather Forecast: Get detailed weather forecasts for specific coordinates

🚀 Features

• ⚡ Get weather alerts by state code

• 📍 Get weather forecasts by latitude/longitude

• 🇺🇸 Supports all US locations via NWS API

• 🔄 Real-time weather data

• 📦 Built with TypeScript and MCP SDK

• 🔧 CLI executable for easy installation and usage

• 🖥️ VS Code integration with MCP support

🛠️ Installation

1. Clone the repository

   git clone <repository-url> cd MCP_Node

2. Install dependencies

   npm install

3. Set up environment variables

   cp .envExample .env

   Edit the .env file with your configuration.

4. Build the project

   npm run build

5. Install globally (optional)

   npm install -g .

   After global installation, you can run the server with:

   weather

⚙️ Configuration

The server requires the following environment variables:

• NWS_API_BASE: Base URL for the National Weather Service API

• USER_AGENT: User agent string for API requests

See .envExample for default values.

🔧 Usage

Running the Server

Option 1: Using npm script

Option 2: Direct node execution

Option 3: Using global installation

VS Code Integration

This server is configured to work with VS Code's MCP support. The configuration is available in .vscode/mcp.json. To use it in VS Code:

1. Ensure the server is built: npm run build

2. The server will be available as salil-weather-mcp-server in your VS Code MCP settings

3. Supported models: GPT-4.1 and Claude Sonnet 4

CLI Usage

After installing globally with npm install -g ., you can use the weather command directly:

The CLI tool provides the same functionality as running the server directly, but with easier access from anywhere on your system.

Available Tools

🚨 get-alerts

Get weather alerts for a specific state.

Parameters:

• state (string): Two-letter state code (e.g., "CA", "NY")

Example:

🌦️ get-forecast

Get weather forecast for a specific location.

Parameters:

• latitude (number): Latitude (-90 to 90)

• longitude (number): Longitude (-180 to 180)

Example:

📁 Project Structure

🔗 Dependencies

Production

• @modelcontextprotocol/sdk: MCP SDK for server implementation

• dotenv: Environment variable management

• zod: Runtime type validation

Development

• typescript: TypeScript compiler

• @types/node: Node.js type definitions

• @types/dotenv: Dotenv type definitions

🔧 CLI Installation & Usage

This package can be installed as a global CLI tool for easy access:

Global Installation

CLI Command

After global installation, the weather command becomes available system-wide:

This starts the MCP server and makes it available for integration with MCP-compatible tools and applications.

Package Distribution

The package is configured with:

• Binary entry point: weather command pointing to ./build/index.js

• ESM modules: Uses modern JavaScript module syntax

• Files whitelist: Only distributes the essential build/ directory

🌐 API Reference

This server uses the National Weather Service API which provides:

• Weather forecasts

• Weather alerts

• Observation data

• Grid point data

Note: The NWS API only supports US locations.

🐛 Error Handling

The server includes comprehensive error handling for:

• Missing environment variables

• Invalid coordinates

• API request failures

• Unsupported locations (non-US)

📝 License

ISC

👥 Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Run tests and build

5. Submit a pull request

🔍 Troubleshooting

Common Issues

1. "Missing required environment variable"

   • Ensure .env file exists and contains required variables

2. "This location may not be supported"

   • The NWS API only supports US locations

   • Verify coordinates are within US boundaries

3. "Server not recognized in VS Code"

   • Ensure the project is built: npm run build

   • Check that .vscode/mcp.json exists and is properly configured

   • Restart VS Code after making configuration changes

4. "Permission denied when installing globally"

   • On Windows: Run PowerShell as Administrator

   • On macOS/Linux: Use sudo npm install -g .

📊 Development

Available Scripts

• Build: Compile TypeScript to JavaScript

  npm run build

• Start: Run the compiled server

  npm start

• Global Install: Install as a global CLI tool

  npm install -g .

VS Code Development

This project includes VS Code configuration for:

• MCP Integration: Pre-configured MCP server settings

• IntelliSense: Enhanced TypeScript support

• Debugging: Launch configurations for debugging

• Spell Check: Custom dictionary for technical terms

File Overview

• src/index.ts: Main application entry point, initializes the MCP server

• src/server.ts: Registers weather tools and handles tool logic

• src/weatherContracts.ts: TypeScript interfaces for API responses

• src/weatherRequest.ts: Utility functions for making API requests