MCP 服务器

Weather MCP Server

Provides current weather conditions and 5-day forecasts for any location using the OpenWeatherMap API. Supports flexible location queries including city names, coordinates, and zip codes.

README

Weather MCP Server

A Model Context Protocol (MCP) server that provides weather information using the OpenWeatherMap API. This server primarily runs in stdio mode (the standard for MCP servers) with an experimental HTTP API mode for testing.

Features

MCP Protocol Support: Full stdio mode support for MCP clients
HTTP API Mode: Experimental simple HTTP API for testing
Current Weather: Get current weather conditions for any location
Weather Forecast: Get weather forecasts up to 5 days ahead
Location Flexibility: Support for city names, coordinates (lat,lon), and zip codes
Docker Support: Containerized deployment with docker-compose
Configurable: YAML-based configuration with environment variable support
Well Tested: Comprehensive test suite with pytest

Prerequisites

Python 3.11 or higher
OpenWeatherMap API key (free tier available at OpenWeatherMap)
Docker (optional, for containerized deployment)

Installation

Using pip

# Clone the repository
git clone https://github.com/dangogh/weather-mcp.git
cd weather-mcp

# Install dependencies
pip install -r requirements.txt

# Install the package
pip install -e .

Using Docker

# Build the Docker image
docker build -t weather-mcp .

# Or use docker-compose (see Docker section below)

Configuration

The server uses a YAML configuration file (config.yaml) with the following structure:

server:
  mode: stdio  # or 'http'
  http:
    host: 0.0.0.0
    port: 8080

weather_api:
  provider: openweathermap
  base_url: https://api.openweathermap.org/data/2.5
  api_key: ${WEATHER_API_KEY}  # Set via environment variable
  units: metric  # or 'imperial' or 'standard'
  timeout: 10

logging:
  level: INFO
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

Environment Variables

WEATHER_API_KEY: Your OpenWeatherMap API key (required)
SERVER_MODE: Override server mode (optional, defaults to config file)

Usage

Running in stdio mode

# Set your API key
export WEATHER_API_KEY="your_api_key_here"

# Run the server
python -m weather_mcp

# Or use the CLI command
weather-mcp

Running in HTTP mode (Experimental)

Note: HTTP mode provides a simple REST API for testing. For production MCP usage, use stdio mode.

# Update config.yaml to set mode: http, or use environment variable
export WEATHER_API_KEY="your_api_key_here"
export SERVER_MODE=http

python -m weather_mcp

The HTTP server will start on http://localhost:8080 with the following endpoints:

GET /: Server information
GET /health: Health check
POST /weather/current: Get current weather (JSON: {"location": "London"})
POST /weather/forecast: Get forecast (JSON: {"location": "London", "days": 3})

Using with Docker

Stdio mode:

# Set your API key in .env file
echo "WEATHER_API_KEY=your_api_key_here" > .env

# Run with docker-compose
docker-compose --profile stdio run weather-mcp-stdio

HTTP mode:

# Run HTTP server
docker-compose --profile http up weather-mcp-http

# The server will be available at http://localhost:8080

Available Tools

get_current_weather

Get current weather conditions for a location.

Parameters:

location (string, required): City name, coordinates (lat,lon), or zip code

Example:

{
  "location": "London"
}

Response includes:

Temperature and "feels like" temperature
Weather description
Humidity percentage
Atmospheric pressure
Wind speed

get_weather_forecast

Get weather forecast for a location up to 5 days ahead.

Parameters:

location (string, required): City name, coordinates (lat,lon), or zip code
days (integer, optional): Number of days to forecast (1-5, default: 3)

Example:

{
  "location": "New York",
  "days": 3
}

Response includes:

Forecast data in 3-hour intervals
Same weather details as current weather for each interval

Development

Running Tests

# Install dev dependencies
pip install -r requirements-dev.txt

# Run tests
pytest

# Run with coverage
pytest --cov=src/weather_mcp --cov-report=html

Code Structure

weather-mcp/
├── src/
│   └── weather_mcp/
│       ├── __init__.py
│       ├── __main__.py       # Entry point
│       ├── config.py          # Configuration management
│       ├── server.py          # MCP server implementation
│       ├── weather_client.py  # Weather API client
│       └── http_server.py     # HTTP streaming server
├── tests/
│   ├── __init__.py
│   ├── test_config.py
│   ├── test_weather_client.py
│   └── test_server.py
├── config.yaml                # Configuration file
├── Dockerfile                 # Docker image definition
├── docker-compose.yml         # Docker compose configuration
├── requirements.txt           # Production dependencies
├── requirements-dev.txt       # Development dependencies
├── setup.py                   # Package setup
└── README.md                  # This file