jackuh105/macau-weather-mcp

Macau Weather MCP Server

A Model Context Protocol (MCP) server that provides real-time weather data for Macau from the Macau Meteorological and Geophysics Bureau (SMG). This server exposes weather information through MCP tools, allowing AI assistants to fetch current weather conditions, daily forecasts, and 7-day weather predictions.

Features

• Real-time Weather Data: Get current weather conditions including temperature, humidity, wind speed.
• Today's Forecast: Retrieve today's weather forecast with detailed descriptions
• 7-Day Forecast: Access extended weather predictions for the next 7 days
• HTTP Streamable MCP: Built using FastMCP with streamable HTTP support for easy integration
• Chinese Language Support: All weather data is provided in Traditional Chinese (繁體中文)

Requirements

• Python 3.12 or higher
• uv package manager (recommended) or pip

Installation

Using uv (Recommended)

# Install dependencies
uv sync

Using pip

# Install dependencies
pip install httpx "mcp[cli]>=1.22.0"

Deployment

Method 1: Using Docker Compose (Recommended)

Using Docker Compose can easily deploy MCP server, and you can optionally deploy MCPO bridge server at the same time.

# start MCP server
docker compose up -d

# If you want to enable MCPO server, please edit docker-compose.yml
# Uncomment mcpo service part, then run:
docker compose up -d

The server will run at http://0.0.0.0:8001/mcp. If MCPO is enabled, it will run at http://0.0.0.0:8000.

# view logs
docker compose logs -f

# stop the service
docker compose down

Method 2: Run directly with Python

Directly run MCP server on the host:

# use uv
uv run weather.py --port 8001

# or use python
python weather.py --port 8001

The server will run at http://0.0.0.0:8001/mcp.

Method 3: Manually build Docker image

If you want to manually build and run Docker container:

# build the image
docker build -t macau-weather-mcp .

# run the container
docker run -d -p 8001:8001 --name macau-weather-mcp macau-weather-mcp

Command line arguments

• --host: bind address (default: 0.0.0.0)
• --port: listen port (default: 8000)

Usage

OpenWebUI

OpenWebUI requires an MCP-to-OpenAI bridge server (MCPO) to convert MCP tools to OpenAI-compatible tool APIs:

uvx mcpo --port 8000 --api-key "top-secret" --server-type "streamable-http" -- http://0.0.0.0:8001/mcp

Then configure the external tool in OpenWebUI settings. For more MCPO deployment methods, refer to the official documentation.

Claude Desktop

Add the following configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "macau-weather": {
      "url": "http://localhost:8001/mcp",
      "transport": "http"
    }
  }
}

Other MCP Clients

Any MCP client that supports HTTP streamable transport can connect to this server at:

http://localhost:8001/mcp

Available Tools

The server provides three MCP tools:

1. get_macau_realtime_weather

獲取澳門當前「整點實況」天氣數據，包含：

• 更新時間
• 當前溫度 (°C)
• 相對濕度 (%)
• 風速 (km/h)
• 風向

2. get_macau_today_forecast

獲取澳門「今日預測」與天氣概述，包含：

• 今日日期
• 天氣形勢
• 今日天氣概況

3. get_macau_7days_forecast

獲取澳門「7天預測」與天氣概述，包含：

• 每日預測溫度範圍
• 每日濕度預測
• 每日天氣描述

Data Source

All weather data is sourced from the Macau Meteorological and Geophysical Bureau (SMG) XML APIs:

• Current Weather: https://xml.smg.gov.mo/c_actual_brief.xml
• Today's Forecast: https://xml.smg.gov.mo/c_forecast.xml
• 7-Day Forecast: https://rss.smg.gov.mo/c_WForecast7days_rss.xml

Technical Details

• Framework: FastMCP (MCP server framework)
• HTTP Client: httpx
• Server: Uvicorn (ASGI server)
• Data Format: XML parsing with ElementTree
• Transport: HTTP Streamable