🌤 Weather MCP Server

Custom MCP Server cung cấp dữ liệu thời tiết thực thời & lịch sử cho các AI Assistant (Claude, Cursor, VS Code Cline…) thông qua giao thức Model Context Protocol (MCP).

✨ Tính năng

🗂 Cấu trúc dự án

custom MCP server/
├── weather_server.py   # MCP Server chính (6 tools)
├── requirements.txt    # Các thư viện cần thiết
└── README.md

📋 Yêu cầu hệ thống

• Python 3.10+

• pip

🚀 Cài đặt

# 1. Di chuyển vào thư mục dự án
cd "e:\TUYENDUNG\custom MCP server"

# 2. (Khuyến nghị) Tạo môi trường ảo
python -m venv .venv
.venv\Scripts\Activate.ps1

# 3. Cài đặt dependencies
pip install -r requirements.txt

🧪 Chạy thử với MCP Inspector

mcp dev weather_server.py

Trình duyệt sẽ tự mở tại http://localhost:5173 — giao diện web để gọi thử từng tool trực tiếp.

⚙️ Tích hợp vào Claude Desktop

1. Mở file cấu hình:

2. Thêm vào mục mcpServers:

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["e:\\TUYENDUNG\\custom MCP server\\weather_server.py"]
    }
  }
}

Nếu dùng môi trường ảo, thay "python" bằng đường dẫn tuyệt đối:

"e:\\TUYENDUNG\\custom MCP server\\.venv\\Scripts\\python.exe"

3. Khởi động lại Claude Desktop — server sẽ được load tự động.

⚙️ Tích hợp vào Cursor / VS Code (Cline)

Thêm vào file cấu hình MCP của extension:

{
  "weather": {
    "command": "python",
    "args": ["e:\\TUYENDUNG\\custom MCP server\\weather_server.py"]
  }
}

📖 Hướng dẫn sử dụng từng Tool

🔍 1. geocode_city — Tìm tọa độ thành phố

Tìm vĩ độ (latitude) và kinh độ (longitude) từ tên thành phố.

geocode_city("Da Nang")

Kết quả mẫu:

Kết quả tìm kiếm cho 'Da Nang':
1. Đà Nẵng, Thành phố Đà Nẵng, Việt Nam
   📍 Tọa độ : lat=16.0544, lon=108.2022
   🏔  Độ cao  : 10 m

🌡 2. get_current_weather — Thời tiết hiện tại theo tọa độ

get_current_weather(latitude=16.0544, longitude=108.2022)

Thông tin trả về: Nhiệt độ, cảm giác thực, độ ẩm, lượng mưa, áp suất, tốc độ & hướng gió, gió giật, tầm nhìn, tình trạng trời.

📅 3. get_forecast — Dự báo thời tiết 1–7 ngày

get_forecast(latitude=16.0544, longitude=108.2022, days=3)

Thông tin trả về theo từng ngày: Nhiệt độ max/min, cảm giác thực, lượng mưa, xác suất mưa, gió max, giờ bình minh/hoàng hôn.

🏙 4. get_weather_by_city — Thời tiết nhanh theo tên thành phố

Gọi 1 bước, không cần tọa độ thủ công.

get_weather_by_city("Ho Chi Minh")

💨 5. get_air_quality — Chất lượng không khí

get_air_quality("Hanoi")

Chỉ số trả về: PM2.5, PM10, CO, NO₂, SO₂, O₃, bụi sa mạc, AQI châu Âu kèm đánh giá mức độ.

📜 6. get_historical_weather — Thời tiết lịch sử

Dữ liệu từ 1940 đến nay, khoảng cách khuyến nghị tối đa 31 ngày/lần gọi.

get_historical_weather(
    city_name="Hanoi",
    start_date="2024-01-01",
    end_date="2024-01-07"
)

Thông tin trả về theo từng ngày: Nhiệt độ max/min, lượng mưa, tốc độ & hướng gió, giờ bình minh/hoàng hôn, tình trạng thời tiết.

💡 Ví dụ thực tế (luồng đầy đủ)

# Bước 1 — Tìm tọa độ Hà Nội
geocode_city("Ha Noi")
# → lat=21.0285, lon=105.8542

# Bước 2 — Xem thời tiết hiện tại
get_current_weather(21.0285, 105.8542)

# Bước 3 — Xem dự báo 3 ngày tới
get_forecast(21.0285, 105.8542, days=3)

# Hoặc gọn hơn (1 bước)
get_weather_by_city("Ha Noi")

# Chất lượng không khí
get_air_quality("Ha Noi")

# Thời tiết tuần trước
get_historical_weather("Ha Noi", "2024-12-01", "2024-12-07")

🗃 Nguồn dữ liệu

Mã thời tiết tuân theo chuẩn WMO (World Meteorological Organization).

📦 Dependencies

mcp[cli]>=1.0.0
httpx>=0.27.0