🌤 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

#	Tool	Mô tả
1	geocode_city	Tìm tọa độ (lat/lon) từ tên thành phố
2	get_current_weather	Thời tiết hiện tại theo tọa độ (nhiệt độ, độ ẩm, gió, áp suất, tầm nhìn…)
3	get_forecast	Dự báo thời tiết theo ngày, tối đa 7 ngày
4	get_weather_by_city	Thời tiết hiện tại theo tên thành phố (tự động geocode, 1 bước)
5	get_air_quality	Chỉ số chất lượng không khí: PM2.5, PM10, CO, NO₂, O₃, SO₂, AQI châu Âu
6	get_historical_weather	Dữ liệu thời tiết lịch sử từ năm 1940 đến nay

---

🗂 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:

Hệ điều hành	Đường dẫn
Windows	%APPDATA%\Claude\claude_desktop_config.json
macOS	~/Library/Application Support/Claude/claude_desktop_config.json

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 độ.

AQI	Mức độ
0–20	🟢 Rất tốt
21–40	🟢 Tốt
41–60	🟡 Trung bình
61–80	🟠 Kém
81–100	🔴 Xấu
> 100	🟣 Rất xấu

---

📜 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

API	Dùng cho
Open-Meteo Forecast API	Thời tiết hiện tại & dự báo
Open-Meteo Geocoding API	Tìm tọa độ thành phố
Open-Meteo Air Quality API	Chất lượng không khí
Open-Meteo Historical API	Dữ liệu lịch sử từ 1940

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

---

📦 Dependencies

mcp[cli]>=1.0.0
httpx>=0.27.0