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

1. Clone this repository:

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

2. Install dependencies:

npm install

Usage

Local Development

Building and Running the Server

1. Build the TypeScript code:

npm run build

2. 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

1. Build the Docker images:

./scripts/docker-build.sh

2. Run in production mode:

./scripts/docker-run.sh production

3. 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

1. MCP Inspector (Web Interface):

   • Navigate to http://localhost:5173
   • Configure your MCP server connection
   • Monitor protocol messages in real-time

2. 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

3. 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>/**"]
   }
   

4. 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

1. For MCP Protocol Issues:

   • Use npm run dev:inspector to monitor MCP messages
   • Check tool calls, responses, and protocol compliance

2. For Code-Level Debugging:

   • Use npm run dev:debug with Chrome DevTools or VS Code
   • Set breakpoints in your TypeScript source files

3. 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:

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

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. 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.