MCP Weather Server
# MCP Weather Server (Node.js)
This repository contains a fully-featured MCP (Model Context Protocol) server built with Node.js and TypeScript that exposes weather-related tools using the US National Weather Service API.
---
## Table of Contents
- [Overview](#overview)
- [Features](#features)
- [Tech Stack](#tech-stack)
- [Getting Started](#getting-started)
- [Project Structure](#project-structure)
- [Environment Setup](#environment-setup)
- [Running the Server](#running-the-server)
- [Usage](#usage)
- [Development & Testing](#development--testing)
- [Best Practices](#best-practices)
- [Contributing](#contributing)
- [License](#license)
---
## Overview
This MCP server provides two main tools:
- `get_alerts` - Retrieve current weather alerts for any US state (by two-letter state code)
- `get_forecast` - Get detailed weather forecast by geographic coordinates
It follows the [Model Context Protocol](https://modelcontextprotocol.io) standards to be compatible with clients such as Claude for Desktop and allows seamless LLM-driven interactions.
---
## Features
- Typed requests and responses using `zod` schemas for argument validation
- Asynchronous API requests with error handling
- Modular tool definitions for scalable code architecture
- Environment variable configuration for flexible deployments
- Integration-ready with popular MCP client tools and MCP Inspector for debugging
---
## Tech Stack
- Node.js (v18+)
- TypeScript
- Zod for schema validations
- `httpx` or `node-fetch` for HTTP requests
- dotenv for environment configuration
- MCP SDK (JavaScript/TypeScript)
- Optional: ts-node or build with `tsc`
---
## Getting Started
### Prerequisites
- Node.js 18 or higher
- npm or yarn
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: get_alerts retrieves weather alerts for a state, while get_forecast provides weather forecasts for a location. There is no overlap or ambiguity between them, making it easy for an agent to select the correct tool based on the need for alerts versus forecasts.
Both tools follow a consistent verb_noun pattern with 'get_' prefix and descriptive nouns (alerts, forecast). This naming convention is predictable and readable, ensuring clarity and ease of use across the tool set.
With only 2 tools, the server feels under-scoped for a weather domain, as it lacks essential operations like current conditions, historical data, or radar information. While the tools are well-defined, the count is too low to provide comprehensive coverage for typical weather-related tasks.
The tool surface is significantly incomplete for a weather server. It includes alerts and forecasts but misses core functionalities such as current weather conditions, historical data, or location-based searches. This will likely cause agent failures when handling broader weather queries.