🌤️ 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
-
Clone the repository
git clone <repository-url> cd MCP_Node -
Install dependencies
npm install -
Set up environment variables
cp .envExample .envEdit the
.envfile with your configuration. -
Build the project
npm run build -
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 APIUSER_AGENT: User agent string for API requests
See .envExample for default values.
🔧 Usage
Running the Server
Option 1: Using npm script
npm start
Option 2: Direct node execution
node build/index.js
Option 3: Using global installation
weather
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:
- Ensure the server is built:
npm run build - The server will be available as
salil-weather-mcp-serverin your VS Code MCP settings - 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:
# Run the MCP server
weather
# The server will start and listen for MCP protocol messages via stdio
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:
{
"state": "CA"
}
🌦️ get-forecast
Get weather forecast for a specific location.
Parameters:
latitude(number): Latitude (-90 to 90)longitude(number): Longitude (-180 to 180)
Example:
{
"latitude": 37.7749,
"longitude": -122.4194
}
📁 Project Structure
MCP_Node/
├── 📄 package.json # Project configuration and dependencies
├── 📄 tsconfig.json # TypeScript configuration
├── � .envExample # Environment variables template
├── 📄 .gitignore # Git ignore patterns
├── 📁 .vscode/ # VS Code configuration
│ ├── 📄 mcp.json # MCP server configuration
│ ├── 📄 settings.json # VS Code workspace settings
│ └── 📄 launch.json # Debug configuration
├── �📁 src/ # Source code
│ ├── 📄 index.ts # Main entry point
│ ├── 📄 server.ts # MCP server setup and tool registration
│ ├── 📄 weatherContracts.ts # TypeScript interfaces
│ └── 📄 weatherRequest.ts # API request utilities
├── 📁 build/ # Compiled JavaScript files
│ ├── 📄 index.js
│ ├── 📄 server.js
│ ├── 📄 weatherContracts.js
│ └── 📄 weatherRequest.js
└── 📄 .env # Environment variables (not in repo)
🔗 Dependencies
Production
@modelcontextprotocol/sdk: MCP SDK for server implementationdotenv: Environment variable managementzod: 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
npm install -g .
CLI Command
After global installation, the weather command becomes available system-wide:
weather
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:
weathercommand 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
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests and build
- Submit a pull request
🔍 Troubleshooting
Common Issues
-
"Missing required environment variable"
- Ensure
.envfile exists and contains required variables
- Ensure
-
"This location may not be supported"
- The NWS API only supports US locations
- Verify coordinates are within US boundaries
-
"Server not recognized in VS Code"
- Ensure the project is built:
npm run build - Check that
.vscode/mcp.jsonexists and is properly configured - Restart VS Code after making configuration changes
- Ensure the project is built:
-
"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
sequenceDiagram
participant User
participant AI as AI (Claude / ChatGPT / Copilot Chat)
participant MCP as Weather MCP Server
participant NWS as National Weather Service API
User->>AI: "What’s the weather in DC tomorrow?"
AI->>MCP: Call tool "get-forecast(lat, lon)"
MCP->>NWS: Fetch forecast data (points + forecast endpoints)
NWS-->>MCP: JSON weather forecast
MCP-->>AI: MCP response { content: [ { type: "text", text: "...forecast..." } ] }
AI-->>User: "Tomorrow in DC: 72°F, sunny with light NW wind."