MCP Weather Server

A Model Context Protocol (MCP) server that provides weather information for any city using the Open-Meteo API.

Overview

This MCP server implements a simple weather tool that allows you to get current weather conditions for any city worldwide. It uses the Open-Meteo geocoding API to resolve city names to coordinates and then fetches current weather data including temperature and wind speed.

Features

City Weather Lookup: Get current weather for any city by name
Geocoding Integration: Automatically resolves city names to coordinates
Current Conditions: Returns temperature and wind speed information
Error Handling: Graceful handling of invalid cities or API failures
MCP Compatible: Built using the official MCP SDK

Prerequisites

Node.js (version 14 or higher)
npm or yarn package manager

Installation

Clone this repository:

git clone <repository-url>
cd mcp-weather-server

Install dependencies:

npm install

Usage

Local Development

Building and Running the Server

Build the TypeScript code:

npm run build

Start the MCP Weather Server:

npm start

Or for development (builds and runs in one command):

npm run dev

The server will start and listen for MCP connections via stdio transport.

Docker Deployment

Quick Start with Docker

Build the Docker images:

./scripts/docker-build.sh

Run in production mode:

./scripts/docker-run.sh production

Run in development mode (with hot reload):

./scripts/docker-run.sh development

Manual Docker Commands

Build production image:

docker build -t mcp-weather-server:latest .

Build development image:

docker build -f Dockerfile.dev -t mcp-weather-server:dev .

Run with Docker Compose (production):

docker-compose up mcp-weather-server

Run with Docker Compose (development):

docker-compose --profile dev up mcp-weather-server-dev

Run standalone container:

docker run -it --rm --name mcp-weather-server mcp-weather-server:latest

Docker Features

Multi-stage builds for optimized production images
Non-root user for enhanced security
Health checks for container monitoring
Resource limits for controlled resource usage
Development mode with hot reload and volume mounting
Node.js Inspector for debugging support
Persistent logging with volume mounts

Debugging

MCP Inspector (Recommended)

The MCP Inspector provides a specialized debugging interface for MCP protocol communications:

Start MCP Inspector:

npm run inspector

Start with build and inspector:

npm run dev:inspector

Access the Inspector:

Open your browser to http://localhost:5173
The inspector provides a web-based interface to:
- Monitor MCP protocol messages
- Inspect tool calls and responses
- Debug server-client communication
- View real-time message flow

Node.js Debugging

Start with Node.js inspector enabled:

npm run dev:debug

Start with inspector and break on first line:

npm run dev:debug-brk

Watch mode for TypeScript compilation:

npm run dev:watch

Docker Debugging

Run development container with all debugging tools:

./scripts/docker-run.sh development

Or manually:

docker-compose --profile dev up mcp-weather-server-dev

This exposes:

Port 9229: Node.js inspector
Port 5173: MCP inspector web interface
Port 3000: Application port (if needed)

Connecting Debuggers

MCP Inspector (Web Interface):
- Navigate to http://localhost:5173
- Configure your MCP server connection
- Monitor protocol messages in real-time
Chrome DevTools:
- Open Chrome and navigate to chrome://inspect
- Click "Configure" and add localhost:9229
- Your Node.js process should appear under "Remote Target"
- Click "inspect" to open DevTools

VS Code:

Add this configuration to your .vscode/launch.json:

{
  "type": "node",
  "request": "attach",
  "name": "Attach to MCP Server",
  "address": "localhost",
  "port": 9229,
  "localRoot": "${workspaceFolder}",
  "remoteRoot": "/app",
  "skipFiles": ["<node_internals>/**"]
}

WebStorm/IntelliJ:
- Create a new "Attach to Node.js/Chrome" configuration
- Set host to localhost and port to 9229

Debug Scripts Explained

inspector: Starts the MCP Inspector web interface
dev:inspector: Builds and starts the MCP Inspector
dev:debug: Starts with Node.js inspector on port 9229
dev:debug-brk: Starts with Node.js inspector and breaks on the first line
dev:watch: Runs TypeScript in watch mode for continuous compilation

Debugging Workflow

For MCP Protocol Issues:
- Use npm run dev:inspector to monitor MCP messages
- Check tool calls, responses, and protocol compliance
For Code-Level Debugging:
- Use npm run dev:debug with Chrome DevTools or VS Code
- Set breakpoints in your TypeScript source files
For Docker Development:
- Use ./scripts/docker-run.sh development
- Access both MCP Inspector (port 5173) and Node.js inspector (port 9229)

Available Tools

`get-weather`

Retrieves current weather information for a specified city.

Parameters:

city (string): The name of the city to get weather for

Example Response:

The current temperature in London is 15°C with a wind speed of 12 km/h.

Integration with MCP Clients

This server can be integrated with any MCP-compatible client. The server exposes the get-weather tool that can be called with a city name parameter.

API Dependencies

This server relies on the following free APIs:

Open-Meteo Geocoding API: For converting city names to coordinates
Open-Meteo Weather API: For fetching current weather data

No API keys are required as Open-Meteo provides free access to their weather data.

Project Structure

mcp-weather-server/
├── src/                    # Source code
│   ├── index.ts           # Main entry point
│   ├── server/            # Server implementation
│   │   └── index.ts       # MCP server setup
│   ├── tools/             # Tool implementations
│   │   └── weather-tool.ts # Weather tool logic
│   ├── types/             # TypeScript type definitions
│   │   └── weather.ts     # Weather-related types
│   └── utils/             # Utility functions
│       └── api.ts         # API client utilities
├── dist/                  # Compiled JavaScript output
├── examples/              # Example configurations
│   └── mcp-config.json   # MCP client configuration example
├── docs/                  # Documentation
├── tests/                 # Test files
├── tsconfig.json         # TypeScript configuration
├── package.json          # Project dependencies and metadata
├── package-lock.json     # Locked dependency versions
├── .gitignore           # Git ignore rules
└── README.md            # This file

Dependencies

@modelcontextprotocol/sdk: Official MCP SDK for building servers
zod: Schema validation library for input validation

Error Handling

The server includes robust error handling for common scenarios:

Invalid City Names: Returns a helpful message when a city cannot be found
API Failures: Gracefully handles network errors or API unavailability
Malformed Requests: Input validation ensures proper request format

Development

Building

This project uses ES modules. Make sure your Node.js version supports ES modules or use a transpiler if needed.

Testing

Currently, no automated tests are included. To test the server:

Start the server
Connect with an MCP client
Call the get-weather tool with various city names

Contributing

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

License

ISC License

Changelog

Version 1.0.0

Initial release
Basic weather lookup functionality
MCP SDK integration
Open-Meteo API integration

Support

For issues or questions, please open an issue in the repository.