臺灣天氣 MCP 伺服器 (Claude 專用)

這是一個專為 Claude AI 設計的 Model Context Protocol (MCP) 伺服器，提供來自中央氣象署 (CWA) 的臺灣天氣預報、警特報和降雨觀測資料。透過此伺服器，Claude Desktop 可以直接存取即時天氣資訊，為用戶提供更智能的天氣相關服務。

功能特色

• 依地點查詢臺灣天氣預報
• 獲取全臺灣活躍的天氣警特報
• 存取各氣象站的降雨資料
• 依地點查看即時天氣觀測資料
• 支援繁體中文地名（例如「臺北市」和「台北市」）

系統需求

• Python 3.8+
• uv 套件管理器
• 中央氣象署 API 金鑰

安裝方式

1. 複製或下載此儲存庫
2. 使用 uv 安裝相依套件：

cd weather
uv pip install -r requirements.txt

3. 在 .env 檔案中設定您的中央氣象署 API 金鑰：

CWA_API_KEY=your_api_key_here

啟動伺服器

可以使用 uv 啟動伺服器：

uv --directory /path/to/your/weather/project run server.py

設定 Claude Desktop

您可以在 Claude Desktop 的設定檔 (config.json) 中加入以下內容，以使用此 MCP 伺服器：

"mcpServers": {
  "taiwan-weather": {
    "command": "/path/to/your/uv",
    "args": [
      "--directory",
      "/path/to/your/weather/project",
      "run",
      "server.py"
    ]
  }
}

此設定將：

1. 使用您本機安裝的 uv 來執行伺服器
2. 將工作目錄設定為您的專案資料夾
3. 使用 server.py 啟動 MCP 伺服器

範例查詢

設定完成後，您可以向 Claude Desktop 提出以下類型的問題：

• "臺北市今天的天氣預報是什麼?"
• "目前臺灣有哪些天氣警報?"
• "高雄市的降雨量是多少?"
• "臺中市的目前氣象觀測數據"
• "臺南市有什麼天氣警特報？它的有效時間是什麼？"

運作原理

此伺服器實現了 Model Context Protocol，讓 Claude Desktop 能夠通過標準化介面查詢外部 API。當您向 Claude 詢問臺灣天氣時，它會：

1. 識別需要外部天氣資料
2. 向 MCP 伺服器發送結構化請求
3. 接收天氣資料
4. 以人類可讀的格式呈現給您

資料來源

所有天氣資料均來自中央氣象署開放資料平臺。

參數說明

MCP 伺服器接受以下參數：

• query_type (必填)：可為 "forecast"（預報）、"warnings"（警特報）、"rainfall"（降雨量）或 "observation"（觀測資料）
• location (選填)：臺灣的地點名稱，例如「臺北市」或「高雄市」（支援繁體「臺」和簡體「台」）
• element (選填)：用於過濾的特定天氣元素

故障排除

如果遇到問題：

1. 確保您的中央氣象署 API 金鑰正確設定在 .env 檔案中
2. 確認 Claude Desktop 設定中的工作目錄路徑與您的實際專案位置相符
3. 檢查 logs 目錄下的相關日誌檔案以獲取詳細的錯誤資訊：
   • 若是天氣預報問題，查看 logs/forecast.log
   • 若是警特報問題，查看 logs/warnings.log
   • 若是觀測資料問題，查看 logs/observation.log
   • 若是 API 連線問題，查看 logs/weather_api.log 和 logs/api_requests.log

最近更新

• 2025-03-09: 修復降雨觀測資料功能，正確處理空地點名稱和限制回傳資料量以提高效能
• 2025-03-05: 改進了警特報資料處理，確保 validTime 欄位（包含 startTime 和 endTime）正確傳遞給前端
• 2025-03-01: 優化了地點名稱匹配邏輯，支援「臺」和「台」的互換使用
• 2025-02-25: 增強了錯誤處理和日誌記錄功能
• 2025-02-20: 改進了不同 API 回應格式的相容性處理
• 2025-02-15: 實作了集中式日誌系統，將不同功能的日誌分類存放

日誌系統

系統採用集中式日誌配置，所有日誌檔案存放於 logs 目錄下：

• server.log：伺服器一般操作日誌
• forecast.log：天氣預報相關操作日誌
• warnings.log：天氣警特報相關操作日誌
• observation.log：天氣觀測資料（含降雨量）相關操作日誌
• weather_api.log：天氣 API 客戶端操作日誌
• api_requests.log：API 請求與回應詳細日誌

每個功能模組使用專屬的日誌記錄器，確保日誌分類清晰：

• 天氣預報功能使用 forecast_logger
• 天氣警特報功能使用 warnings_logger
• 天氣觀測功能使用 observations_logger
• 伺服器一般操作使用 server_logger
• API 客戶端使用 weather_api_logger 和 api_requests_logger

此設計便於問題排查與系統監控，可快速定位特定功能的運作狀況。

授權條款

本專案採用 MIT 授權條款。