agentventure/mcp_server_node_getting_started

Weather MCP Server

A Model Context Protocol (MCP) server that provides weather information using the National Weather Service API. This server exposes two tools for retrieving weather alerts and forecasts for US locations.

Features

• Weather Alerts: Get active weather alerts for any US state using 2-letter state codes
• Weather Forecasts: Get detailed weather forecasts for specific coordinates (latitude/longitude)
• Built with TypeScript and the MCP SDK
• Uses the National Weather Service API (no API key required)

Prerequisites

• Node.js (v16 or higher)
• npm or yarn
• An MCP-compatible client (like Claude Desktop or Warp)

Installation

1. Clone or download this repository
2. Install dependencies:

npm install

Building

Build the TypeScript source code:

npm run build

This will:

• Compile TypeScript files from src/ to build/
• Make the output executable with proper permissions

Usage

Available Tools

get_alerts

Get weather alerts for a US state.

Parameters:

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

Example:

Get weather alerts for California

get_forecast

Get weather forecast for specific coordinates.

Parameters:

• latitude (number): Latitude (-90 to 90)
• longitude (number): Longitude (-180 to 180)

Example:

Get weather forecast for latitude 37.7749, longitude -122.4194

MCP Configuration

To use this server with an MCP client, add the following configuration:

For Claude Desktop

Add to your Claude Desktop MCP configuration file:

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/absolute/path/to/weather/build/index.js"]
    }
  }
}

For Warp

Add to your Warp MCP configuration:

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/absolute/path/to/weather/build/index.js"]
    }
  }
}

Important: Replace /absolute/path/to/weather/build/index.js with the actual absolute path to your built server file.

Example Usage in Chat

Once configured with your MCP client, you can use natural language requests:

• "What are the current weather alerts in California?"
• "Get the weather forecast for San Francisco" (you may need to provide coordinates)
• "Show me weather alerts for Texas"
• "What's the forecast for coordinates 40.7128, -74.0060?" (New York City)

Development

Project Structure

weather/
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript output
├── package.json          # Project configuration
├── tsconfig.json         # TypeScript configuration
├── .gitignore           # Git ignore rules
└── README.md            # This file

Making Changes

1. Edit the TypeScript source in src/index.ts
2. Rebuild the project: npm run build
3. Restart your MCP client to pick up changes

API Details

This server uses the National Weather Service API:

• Alerts: https://api.weather.gov/alerts?area={STATE_CODE}
• Forecasts: https://api.weather.gov/points/{LAT},{LON} → {forecast_url}

The NWS API only supports US locations and doesn't require an API key.

Troubleshooting

Common Issues

1. "Failed to retrieve grid point data": This usually means the coordinates are outside the US or in an unsupported area.

2. "Failed to retrieve alerts data": Check your internet connection and verify the state code is valid (2 letters).

3. Server not responding: Make sure you've built the project with npm run build and the path in your MCP configuration is correct.

Debugging

The server logs errors to stderr, which should be visible in your MCP client's logs or console.

License

This project is licensed under the ISC License - see the package.json file for details.

Contributing

This project was built following the Model Context Protocol quickstart guide. Feel free to extend it with additional weather features or improve the existing functionality.

This implementation follows the quickstart tutorial from Model Context Protocol Guide, providing a comprehensive example of building an MCP server using Node.js to handle weather data.