Skip to main content
Glama
taiwan-weather-mcp

taiwan-weather-mcp

by kuotunyu

taiwan-weather-mcp

CI coverage License: MIT Python 3.11+

台灣即時天氣預報、天氣特報與有感地震查詢的 MCP(Model Context Protocol)server, 讓 Claude Desktop / Claude Code 直接查中央氣象署的開放資料。

English: An MCP server for Taiwan weather — 36-hour forecasts, active weather warnings, and recent felt earthquakes — backed by Central Weather Administration (CWA) open data. Tool descriptions and responses are in Traditional Chinese. Requires a free CWA API key via the CWA_API_KEY environment variable.

使用官方 mcp Python SDK 的 FastMCP (SDK v2 起更名為 MCPServer,本專案使用穩定版 v1 系列),stdio transport。 資料來源:中央氣象署開放資料平臺。

提供的工具

工具

說明

參數

get_forecast

某縣市未來 36 小時天氣預報(天氣現象、降雨機率、氣溫區間、舒適度)。縣市名稱有模糊對應:「台中」→「臺中市」、「Taipei」→「臺北市」;「新竹」「嘉義」會同時回傳市與縣

city:縣市名稱

get_weather_warnings

目前生效中的天氣特報(颱風、豪雨、低溫、強風等),依特報種類彙整影響縣市;沒有特報時會明確說明

無

get_recent_earthquakes

最近幾筆顯著有感地震(時間、規模、深度、震央、各縣市最大震度摘要)

limit:筆數 1–10,預設 5

對應的 CWA dataset:F-C0032-001(36 小時預報)、W-C0033-001(天氣特報)、E-A0015-001(顯著有感地震報告)。

除了 tools 之外也提供其他 MCP primitive:

  • Resource taiwan-weather://cities:22 個可查詢縣市的官方名稱清單。

  • Prompt weather_briefing(city):「查詢並播報某縣市天氣」的提示詞範本。

  • 三個工具都帶 readOnlyHint annotation(只讀公開資料、不改變任何狀態)。

Related MCP server: roc-cwa-mcp

1. 申請 CWA API 授權碼(免費)

  1. 到 中央氣象署開放資料平臺 點右上角「登入/註冊」,註冊會員(一般 Email 即可,即時核發)。

  2. 登入後到 會員資訊 → API授權碼。

  3. 點「取得授權碼」,複製形如 CWA-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX 的字串。

授權碼只透過環境變數 CWA_API_KEY 讀取,不要寫進任何檔案。 本機開發可複製 .env.example 為 .env 填入(.env 已被 .gitignore 排除)。

2. 安裝

先安裝 uv:

# Windows(PowerShell)
winget install astral-sh.uv
# WSL / Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

然後:

git clone https://github.com/kuotunyu/taiwan-weather-mcp.git
cd taiwan-weather-mcp
uv sync          # 會自動下載 Python 3.12 與所有依賴

3. 在 Claude Code 使用

最快(免 clone,只要裝好 uv):

claude mcp add taiwan-weather -e CWA_API_KEY=你的授權碼 -- uvx --from git+https://github.com/kuotunyu/taiwan-weather-mcp taiwan-weather-mcp

或使用本機 clone:

# Windows(PowerShell,路徑換成你 clone 的位置)
claude mcp add taiwan-weather -e CWA_API_KEY=你的授權碼 -- uv --directory "C:\path\to\taiwan-weather-mcp" run server.py

# WSL / Linux / macOS(repo 需 clone 在該環境內)
claude mcp add taiwan-weather -e CWA_API_KEY=你的授權碼 -- uv --directory ~/taiwan-weather-mcp run server.py

加好後用 claude mcp list 確認,然後在對話中直接問「台中明天天氣如何?」即可。

4. 在 Claude Desktop(Windows)使用

設定檔位置:%APPDATA%\Claude\claude_desktop_config.json (Claude Desktop → 設定 → 開發人員 → 編輯設定檔)。

改完設定檔請從系統匣完全結束 Claude Desktop 再重開;檔案須以 UTF-8 儲存。

寫法 A:server 在 WSL 內,透過 wsl.exe 橋接

前置(在 WSL 內執行一次):

curl -LsSf https://astral.sh/uv/install.sh | sh        # 安裝 uv
git clone https://github.com/kuotunyu/taiwan-weather-mcp.git ~/taiwan-weather-mcp
cd ~/taiwan-weather-mcp && uv sync

repo 請放 WSL 自己的檔案系統(如 ~/),不要放 /mnt/c/...,速度差很多。

{
  "mcpServers": {
    "taiwan-weather": {
      "command": "wsl.exe",
      "args": [
        "-e", "bash", "-c",
        "CWA_API_KEY=你的授權碼 exec $HOME/.local/bin/uv --directory $HOME/taiwan-weather-mcp run server.py"
      ]
    }
  }
}

兩個常見地雷這個寫法都避開了:

  • Claude Desktop 的 env 區塊不會自動穿透 WSL 邊界,所以金鑰用行內環境變數帶入。 若不想讓金鑰出現在 args,可改用 WSLENV 轉送:

    {
      "mcpServers": {
        "taiwan-weather": {
          "command": "wsl.exe",
          "args": ["-e", "/home/你的WSL帳號/.local/bin/uv",
                   "--directory", "/home/你的WSL帳號/taiwan-weather-mcp",
                   "run", "server.py"],
          "env": { "CWA_API_KEY": "你的授權碼", "WSLENV": "CWA_API_KEY/u" }
        }
      }
    }
  • 用非登入 shell(bash -c 而非 bash -lc)+ uv 絕對路徑:登入 shell 的 profile 若有任何輸出, 會污染 stdout 打斷 MCP 協定。

寫法 B:直接在 Windows 端用 Python/uv 執行

前置:Windows 裝好 uv(見上),repo clone 在 Windows 檔案系統並 uv sync。

{
  "mcpServers": {
    "taiwan-weather": {
      "command": "C:\\Users\\你的帳號\\.local\\bin\\uv.exe",
      "args": ["--directory", "C:\\path\\to\\taiwan-weather-mcp", "run", "server.py"],
      "env": { "CWA_API_KEY": "你的授權碼" }
    }
  }
}

寫法 B':Windows 端免 clone(uvx 直接從 GitHub 執行)

只要裝好 uv,不需要 clone repo(首次啟動會自動下載,之後走快取):

{
  "mcpServers": {
    "taiwan-weather": {
      "command": "C:\\Users\\你的帳號\\.local\\bin\\uvx.exe",
      "args": ["--from", "git+https://github.com/kuotunyu/taiwan-weather-mcp", "taiwan-weather-mcp"],
      "env": { "CWA_API_KEY": "你的授權碼" }
    }
  }
}

command 建議填 uv 的完整路徑(Claude Desktop 不一定繼承你的 PATH)。 在 PowerShell 執行 (Get-Command uv).Source 查詢實際位置 (winget 安裝的路徑會在 ...\WinGet\Packages\astral-sh.uv_...\uv.exe)。 JSON 內的反斜線要寫成 \\。

5. 示範提問

安裝後可使用以下提問;回覆內容以當次 CWA 資料為準。

提問

對應工具

回覆內容

台中這兩天天氣怎樣?

get_forecast(city="台中")

未來 36 小時各時段的天氣、降雨機率、氣溫與舒適度

現在有什麼天氣警報嗎?

get_weather_warnings()

生效特報與影響縣市;無特報時會明確說明

最近有地震嗎?

get_recent_earthquakes()

最近有感地震的時間、規模、深度、震央與震度摘要

6. 開發

uv run pytest                                          # 離線測試(fixtures)
uv run ruff check . && uv run ruff format .            # lint / 格式化
uv run --env-file .env python scripts/explore_api.py   # 實測 CWA API、重錄 fixtures
uv run --env-file .env python scripts/smoke_test.py    # stdio 起 server 實呼叫三個 tool

專案結構:

server.py                  # 薄轉接層(讓 uv run server.py 可用)
taiwan_weather/
  server.py                # MCP server 本體(FastMCP + 3 個 tool、console script 進入點)
  api.py                   # CWA API 呼叫(唯一做網路 I/O 的模組)
  cities.py                # 縣市名稱模糊對應(純函式)
  formatters.py            # JSON → 精簡繁中文字(純函式)
  errors.py                # 錯誤類別與所有使用者訊息
scripts/explore_api.py     # 實測 API、錄製 tests/fixtures
scripts/smoke_test.py      # stdio 端對端煙霧測試
tests/                     # pytest(unit + in-memory 整合測試)

貢獻方式見 CONTRIBUTING.md,版本紀錄見 CHANGELOG.md。

資料來源與授權

安全性

  • 授權碼只從環境變數 CWA_API_KEY 讀取,程式碼與 repo 中不含任何金鑰。

  • .env 已被 .gitignore 排除;.env.example 僅含佔位字串。

Available Tools

3 tools
get_forecastA
Read-only

查詢台灣某縣市未來 36 小時天氣預報。

回傳三個時段的天氣現象、降雨機率、氣溫區間與舒適度。
縣市名稱接受常見寫法,例如「台中」「臺北市」「高雄」「Taipei」;
「新竹」「嘉義」同時對應市與縣,會一次回傳兩者。

Args:
    city: 縣市名稱(台灣 22 縣市,中英文皆可)。

Inputs: city (required). Returns: result

get_recent_earthquakesA
Read-only

查詢最近幾筆顯著有感地震報告。

每筆包含發生時間、規模、深度、震央位置與各縣市最大震度摘要。

Args:
    limit: 回傳筆數(1–10,預設 5)。

Inputs: limit. Returns: result

get_weather_warningsA
Read-only

查詢目前生效中的天氣特報(颱風、豪雨、大雨、低溫、強風等)。

依特報種類彙整影響縣市與有效時間;若全臺皆無生效中的警特報, 會明確回覆「目前全臺無生效中的天氣警特報」。

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.6/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool covers a distinctly separate concern: forecasts, active weather warnings, and recent earthquakes. There is no overlap in purpose or return data, so an agent can select the right tool without ambiguity.

    Naming Consistency5/5

    All three tools follow the same get_<noun> pattern with clear, descriptive names. The naming is consistent and predictable.

    Tool Count4/5

    Three tools is at the lower end of a reasonable range, but each covers a meaningful aspect of Taiwan weather information. The count feels slightly minimal rather than bloated, which is appropriate for a focused weather server.

    Completeness4/5

    The server covers forecasts, warnings, and earthquakes, which are the most commonly requested Taiwan weather data. A minor gap is the lack of current observed weather conditions or air quality, but the existing tools cover the core domain well.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides read-only access to Taiwan's Central Weather Administration (CWA) Open Data API, offering 36 tools across 7 categories including weather forecasts, observations, earthquakes, and astronomy.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables to access Taiwan Central Weather Administration data, including 3-day and 1-week weather forecasts for counties/cities and historical rainfall data.
      3
      MIT