MOlechowski/mcp-weather-server

MCP Weather Server

A Model Context Protocol (MCP) server that provides weather forecasting capabilities using the US National Weather Service API.

Features

• Get weather forecasts by latitude/longitude coordinates
• Formatted weather data including temperature, wind, and conditions
• Built with TypeScript and the MCP SDK
• Fast and lightweight

Prerequisites

• Node.js 18+ or Bun 1.0+
• npm or Bun package manager

Installation

# Using npm
npm install

# Using Bun (recommended)
bun install

Building

# Using npm
npm run build

# Using Bun
bun run build

Usage

As an MCP Server

The server communicates via stdio and exposes a get_forecast tool that accepts latitude and longitude coordinates.

# Run the server
node build/index.js

# Or with Bun
bun build/index.js

MCP Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/absolute/path/to/build/index.js"],
      "description": "Weather MCP Server - provides weather forecasts"
    }
  }
}

For Claude Desktop on macOS, add to: ~/Library/Application Support/Claude/claude_desktop_config.json

Tool API

The server exposes one tool:

get_forecast

Get the weather forecast for a specific location.

Parameters:

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

Returns: Formatted weather forecast including:

• Period name (Today, Tonight, etc.)
• Temperature and unit
• Wind speed and direction
• Short forecast description

Example:

{
  "tool": "get_forecast",
  "arguments": {
    "latitude": 40.7128,
    "longitude": -74.0060
  }
}

Development

Project Structure

mcp-weather-server/
├── src/
│   └── index.ts        # Main server implementation
├── build/              # Compiled JavaScript
├── package.json        # Dependencies and scripts
├── tsconfig.json       # TypeScript configuration
└── README.md          # This file

Testing

# Run tests (once implemented)
npm test

# With Bun
bun test

Debugging

The server uses Winston logger configured to write to stderr. All logs go to stderr to avoid interfering with the MCP protocol communication on stdout.

To debug:

1. Check stderr output for log messages
2. Use the MCP Inspector tool: npx @modelcontextprotocol/inspector build/index.js
3. Add more logging at key points (remember: stderr only!)

Limitations

• US Only: The National Weather Service API only provides data for US locations
• International locations will return an error

Technologies

• TypeScript
• MCP SDK (@modelcontextprotocol/sdk)
• Axios for HTTP requests
• Winston for logging
• Zod for schema validation

License

ISC

Author

Michal Olechowski

Repository

https://github.com/MOlechowski/mcp-weather-server

Contributing

Issues and pull requests are welcome!