Weather CLI with MCP Server Integration

Overview

Weather CLI is a command-line tool and server application that provides real-time weather information for any location globally. It integrates with the Model Control Protocol (MCP) to offer a standardized service interface, making it easy to deploy and integrate with other systems. The tool uses the wttr.in API to fetch weather data and supports both command-line and server modes.

Key Features

• Fetch real-time weather data for any location globally.
• Default location: Beijing.
• Supports Chinese weather descriptions.
• Displays detailed weather information (temperature, humidity, wind speed, etc.).
• No API key required.
• Supports both command-line and MCP server modes.

What is MCP?

Model Control Protocol (MCP) is a lightweight service protocol designed for building and deploying machine learning model services. In this project, MCP is used to:
- Provide standardized service interfaces.
- Support asynchronous operations.
- Facilitate integration with other systems.
- Support multiple transport protocols (stdio, TCP, WebSocket, etc.).

Installation

To install the Weather CLI, follow these steps:

# Clone the repository
git clone https://github.com/liye71023326/weather-cli.git
cd weather-cli

# Install using uv (recommended)
uv pip install -e .

# Or install using pip
pip install -e .

Usage

1. Command-Line Mode

Use the weather-cli command to fetch weather data:

# Fetch weather for Beijing (default)
weather-cli forecast

# Fetch weather for Shanghai
weather-cli forecast --latitude 31.2304 --longitude 121.4737

# Fetch weather for Guangzhou
weather-cli forecast --latitude 23.1291 --longitude 113.2644

2. MCP Server Mode

Start the Server

# Method 1: Run directly using Python
python run_server.py

# Method 2: Run using MCP CLI tool
mcp run weather

Query Weather Using MCP Client

In another terminal:

# Fetch weather for Beijing (default coordinates)
mcp call weather get_forecast

# Fetch weather for a specific location
mcp call weather get_forecast --latitude 31.2304 --longitude 121.4737

Server API Documentation

1. get_forecast Endpoint
2. Function: Fetches weather forecasts for a specified location.
3. Parameters:
   • latitude: Latitude, range -90 to 90 (default: 39.9042, Beijing).
   • longitude: Longitude, range -180 to 180 (default: 116.4074, Beijing).

4. Returns: Weather information string, including:

   • City name
   • Current weather conditions
   • Temperature and feels-like temperature
   • Humidity and pressure
   • Wind direction and speed
   • Visibility and cloud cover
   • Precipitation

5. get_alerts Endpoint

6. Function: Fetches weather alerts (not yet implemented).
7. Parameters:
   • state: Region code.
8. Returns: Alert information.

Common City Coordinates

Here are the coordinates for some commonly searched cities:
- Beijing: 39.9042, 116.4074 (default)
- Shanghai: 31.2304, 121.4737
- Guangzhou: 23.1291, 113.2644
- Shenzhen: 22.5431, 114.0579
- Chengdu: 30.5728, 104.0668
- Wuhan: 30.5928, 114.3055
- Xi'an: 34.3416, 108.9398
- Hangzhou: 30.2741, 120.1551

Development

System Requirements

• Python 3.13 or higher.
• httpx: For asynchronous HTTP requests.
• mcp[cli]: MCP protocol implementation.

Project Structure

weather-cli/
├── weather/
│   ├── __init__.py  # MCP server implementation and weather API integration
│   └── cli.py       # Command-line interface implementation
├── run_server.py    # MCP server startup script
├── pyproject.toml   # Project configuration
├── .gitignore       # Git ignore configuration
└── README.md        # This file

Extending the Project

You can extend the project by:
1. Adding new weather data sources.
2. Implementing additional weather-related features (e.g., future forecasts).
3. Supporting additional transport protocols.
4. Implementing data caching mechanisms.
5. Adding weather alert functionality.
6. Including more default city coordinates.

Contributing

Contributions are welcome! Please submit issues and pull requests to improve the project.

License

This project is licensed under the MIT License.

Acknowledgments

• wttr.in: For providing weather data.
• httpx: For the asynchronous HTTP client.
• mcp: For the MCP protocol implementation.
• FastMCP: For the fast MCP framework.