Weather MCP Server

A Model Context Protocol (MCP) server for weather data with OpenAPI support. This server provides weather information from OpenWeatherMap API and can be used by LLM agents through MCP.

Features

• MCP stdio transport for LLM agent integration
• HTTP REST API with OpenAPI 3.0 specification
• 4 weather tools:
  1. Get current weather by city
  2. Get current weather by coordinates
  3. Get weather forecast (5-day, 3-hour intervals)
  4. Get temperature range summary
• Mock data support for testing without API key
• TypeScript implementation with full type safety

Installation

cd weather-mcp-server
npm install
npm run build

Usage

1. MCP Server (stdio transport)

Run the MCP server for LLM agents:

npm start

Or in development mode:

npm run dev

2. HTTP Server with OpenAPI

Run the HTTP server with REST API:

npm run dev:http

The server will start on http://localhost:3000 with:

• /health - Health check endpoint
• /openapi - OpenAPI specification
• /api/v1/weather/current/{city} - Current weather by city
• /api/v1/weather/current/coordinates - Current weather by coordinates
• /api/v1/weather/forecast/{city} - Weather forecast

3. Configuration

Set your OpenWeatherMap API key (optional - mock data will be used if not provided):

export OPENWEATHER_API_KEY=your_api_key_here

Or create a .env file:

OPENWEATHER_API_KEY=your_api_key_here

MCP Tools

The server provides the following MCP tools:

Tool Name	Description	Parameters
weather_get_current_by_city	Get current weather by city	city: string
weather_get_current_by_coords	Get current weather by coordinates	latitude: number, longitude: number
weather_get_forecast	Get weather forecast	city: string, days?: number (1-10, default: 5)
weather_get_temperature_range	Get temperature range summary	city: string

API Endpoints

HTTP REST API

All endpoints return JSON with the following structure:

{
  "success": true,
  "data": { ... }
}

1. Current Weather by City

GET /api/v1/weather/current/{city}

Example:

curl http://localhost:3000/api/v1/weather/current/London

2. Current Weather by Coordinates

GET /api/v1/weather/current/coordinates?lat={latitude}&lon={longitude}

Example:

curl "http://localhost:3000/api/v1/weather/current/coordinates?lat=51.5074&lon=-0.1276"

3. Weather Forecast

GET /api/v1/weather/forecast/{city}?days={days}

Example:

curl "http://localhost:3000/api/v1/weather/forecast/New%20York?days=3"

Testing

Run the test suite:

npm test

Run MCP inspector for debugging:

npm run inspect

Project Structure

weather-mcp-server/
├── src/
│   ├── index.ts              # MCP stdio server
│   ├── http-server.ts        # HTTP server with OpenAPI
│   ├── types/
│   │   └── weather.ts        # TypeScript types and Zod schemas
│   ├── utils/
│   │   └── weather-client.ts # OpenWeatherMap API client
│   └── tools/
│       └── weather-tools.ts  # MCP tool definitions
├── dist/                     # Compiled JavaScript
├── test/
│   └── test.js              # Test suite
├── package.json
├── tsconfig.json
└── README.md

Dependencies

• @modelcontextprotocol/sdk - MCP SDK for TypeScript
• express - HTTP server framework
• axios - HTTP client for API calls
• zod - Schema validation
• typescript - TypeScript compiler

License

MIT