MCP Server THSRC - 台灣高鐵資訊查詢服務

這是一個基於 Model Context Protocol (MCP) 的台灣高鐵資料查詢服務器，提供即時的高鐵時刻表、車站資訊、班次狀態和座位查詢功能。

功能特色

• 🚄 完整的高鐵資料查詢：時刻表、即時班次、座位狀態
• 🌐 多語言支援：支援中文站名、英文站名及ID查詢
• 🔄 即時資料：整合 TDX (運輸資料流通服務) API
• 📱 MCP 標準：相容所有支援 MCP 的應用程式

安裝方式

🚀 快速開始（推薦）

適用所有平台（Windows/macOS/Linux）

直接使用 npx，無需複雜安裝步驟：

npx @physictim/mcp-server-thsrc --help

📋 系統需求

• Node.js 14.0+
• Python 3.8+
• TDX API 金鑰（免費申請）

Windows 完整安裝指南

步驟 1：安裝 Node.js

1. 前往 nodejs.org 下載 LTS 版本
2. 執行安裝程式，確保勾選 "Add to PATH"
3. 重新開啟命令提示字元，驗證安裝：

   node --version
   npm --version

步驟 2：安裝 Python

選項 A：從官網安裝（推薦）

1. 前往 python.org 下載最新版本
2. 執行安裝程式，重要：勾選 "Add Python to PATH"
3. 驗證安裝：

   py --version
   python --version

選項 B：使用 Microsoft Store

1. 開啟 Microsoft Store
2. 搜尋 "Python" 並安裝
3. 驗證安裝：

   python --version

選項 C：使用 winget

winget install Python.Python.3.12

步驟 3：取得 TDX API 金鑰

1. 前往 TDX運輸資料流通服務平臺
2. 註冊帳號並登入
3. 前往「會員中心」→「應用服務」→「API金鑰管理」
4. 取得：
   • Client ID
   • Client Secret

步驟 4：設定 Claude Desktop

1. 找到設定檔位置：

   Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 編輯設定檔（如果檔案不存在，請建立）：

   {
     "mcpServers": {
       "thsrc": {
         "command": "npx",
         "args": ["-y", "@physictim/mcp-server-thsrc@latest"],
         "env": {
           "TDX_CLIENT_ID": "在這裡貼上你的 Client ID",
           "TDX_CLIENT_SECRET": "在這裡貼上你的 Client Secret"
         }
       }
     }
   }

3. 重啟 Claude Desktop

步驟 5：驗證安裝

在 Claude Desktop 中輸入：

請查詢台灣高鐵車站列表

如果看到車站資訊，表示安裝成功！

替代安裝方法

方法 2：使用 pipx（進階用戶）

# 安裝 pipx
python -m pip install --user pipx
python -m pipx ensurepath

# 從 GitHub 安裝
pipx install git+https://github.com/physictim/thsrc_mcp.git

方法 3：手動安裝

# 複製專案
git clone https://github.com/physictim/thsrc_mcp.git
cd thsrc_mcp

# 建立虛擬環境
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 安裝依賴
pip install -r requirements.txt

整合到 Claude Desktop

1. 取得 TDX API 金鑰

前往 TDX運輸資料流通服務平臺 註冊並取得：

• Client ID
• Client Secret

2. 配置 Claude Desktop

找到 Claude Desktop 的設定檔：

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

3. 編輯設定檔

在 claude_desktop_config.json 中加入以下設定：

如果你使用 npx（推薦）：

Windows/macOS/Linux 通用：

{
  "mcpServers": {
    "thsrc": {
      "command": "npx",
      "args": ["-y", "@physictim/mcp-server-thsrc"],
      "env": {
        "TDX_CLIENT_ID": "在這裡貼上你的 Client ID",
        "TDX_CLIENT_SECRET": "在這裡貼上你的 Client Secret"
      }
    }
  }
}

如果你使用 pipx 安裝：

{
  "mcpServers": {
    "thsrc-mcp": {
      "command": "mcp-server-thsrc",
      "env": {
        "TDX_CLIENT_ID": "在這裡貼上你的 Client ID",
        "TDX_CLIENT_SECRET": "在這裡貼上你的 Client Secret"
      }
    }
  }
}

如果你手動安裝：

{
  "mcpServers": {
    "thsrc-mcp": {
      "command": "/path/to/your/python3",
      "args": ["/path/to/your/thsrc.py"],
      "env": {
        "TDX_CLIENT_ID": "在這裡貼上你的 Client ID",
        "TDX_CLIENT_SECRET": "在這裡貼上你的 Client Secret"
      }
    }
  }
}

4. 重啟 Claude Desktop

重新啟動 Claude Desktop，MCP 服務器將會自動載入。

5. 驗證連線

在 Claude Desktop 中輸入：

請幫我查詢台灣高鐵車站列表

如果設定成功，Claude 將會使用 MCP 工具查詢並返回高鐵車站資訊。

使用範例

設定完成後，您可以在 Claude Desktop 中直接使用自然語言查詢：

• "查詢明天台北到左營的高鐵班次"
• "台中車站現在有哪些班次？"
• "823車次明天的詳細資訊"
• "台北到高雄還有座位嗎？"

Claude 會自動調用相應的 MCP 工具來取得即時資料。

可用工具

1. 車站列表查詢

get_thsr_stations()

取得所有台灣高鐵車站資訊。

2. 時刻表查詢

get_thsr_timetable("台北", "左營", "2024-01-01")

查詢指定路線和日期的班次時刻表。

參數說明：

• origin_station: 起站（支援中文站名如"台北"或站點ID如"1000"）
• destination_station: 迄站（支援中文站名如"左營"或站點ID如"1070"）
• travel_date: 乘車日期（YYYY-MM-DD格式）

3. 即時班次查詢

get_thsr_live_schedule("台北")

取得指定車站的即時班次狀態。

參數說明：

• station: 車站名稱或ID

4. 特定班次資訊

get_thsr_train_info("823", "2024-01-01")

查詢特定車次的詳細資訊。

參數說明：

• train_no: 車次號碼
• travel_date: 乘車日期（YYYY-MM-DD格式）

5. 剩餘座位查詢

get_thsr_available_seats("台北", "左營", "2024-01-01")

查詢指定路線的剩餘座位狀態。

參數說明：

• origin_station: 起站
• destination_station: 迄站
• travel_date: 乘車日期

更新頻率：

• 當日查詢：每10分鐘更新
• 其他日期：每日10:00、16:00、22:00更新

支援車站

資源

thsr://stations

提供車站資訊的 MCP 資源，可在支援 MCP 的應用程式中直接存取。

使用範例

查詢台北到左營的班次

# 使用中文站名
result = await get_thsr_timetable("台北", "左營", "2024-01-01")

# 使用英文站名
result = await get_thsr_timetable("Taipei", "Zuoying", "2024-01-01")

# 使用站點ID
result = await get_thsr_timetable("1000", "1070", "2024-01-01")

查詢台北車站即時班次

result = await get_thsr_live_schedule("台北")

查詢座位狀態

result = await get_thsr_available_seats("台北", "左營", "2024-01-01")

注意事項

1. API 限制：請遵守 TDX API 的使用限制
2. 認證：確保正確設定 TDX API 金鑰
3. 日期格式：日期必須使用 YYYY-MM-DD 格式
4. 站名輸入：支援中英文站名，大小寫敏感

錯誤處理

• 無效站名：會拋出 ValueError 錯誤
• API 認證失敗：請檢查環境變數設定
• 網路連線問題：請確認網路連線狀態

🛠️ 故障排除

Windows 常見問題

問題 1：找不到 Python

症狀：

錯誤：找不到 Python 3.8+ 版本

解決方案：

1. 重新安裝 Python：

   # 檢查當前 Python 版本
   py --version
   python --version
   
   # 如果沒有輸出，需要安裝 Python
   winget install Python.Python.3.12

2. 手動指定 Python 路徑： 在 Claude Desktop 設定中加入 PYTHON_PATH：

   {
     "mcpServers": {
       "thsrc": {
         "command": "npx",
         "args": ["-y", "@physictim/mcp-server-thsrc@latest"],
         "env": {
           "PYTHON_PATH": "C:\\Python313\\python.exe",
           "TDX_CLIENT_ID": "你的 Client ID",
           "TDX_CLIENT_SECRET": "你的 Client Secret"
         }
       }
     }
   }

   常見 Python 路徑：

   • C:\Python313\python.exe
   • C:\Users\[使用者名稱]\anaconda3\python.exe
   • C:\Users\[使用者名稱]\AppData\Local\Programs\Python\Python313\python.exe

3. 清除 npm 緩存：

   npm cache clean --force

問題 2：權限錯誤

症狀：

安裝依賴失敗
permission denied

解決方案：

1. 以管理員身份執行：

   • 右鍵點擊「命令提示字元」
   • 選擇「以系統管理員身分執行」

2. 使用用戶安裝：

   py -m pip install --user httpx fastmcp python-dotenv

問題 3：編碼問題

症狀：

UnicodeDecodeError
字元編碼錯誤

解決方案：

1. 設定環境變數：

   set PYTHONIOENCODING=utf-8

2. 在 Claude Desktop 設定中加入：

   {
     "mcpServers": {
       "thsrc": {
         "command": "npx",
         "args": ["-y", "@physictim/mcp-server-thsrc@latest"],
         "env": {
           "PYTHONIOENCODING": "utf-8",
           "TDX_CLIENT_ID": "你的 Client ID",
           "TDX_CLIENT_SECRET": "你的 Client Secret"
         }
       }
     }
   }

問題 4：防毒軟體阻擋

症狀：安裝或執行時被防毒軟體阻擋

解決方案：

1. 暫時停用即時保護
2. 將 Python 和 Node.js 加入白名單
3. 將專案資料夾加入排除清單

macOS/Linux 常見問題

Python 版本管理

如果系統有多個 Python 版本：

# 使用 pyenv 管理版本
pyenv install 3.12.0
pyenv global 3.12.0

# 或直接指定路径
export PYTHON_PATH=/usr/local/bin/python3.12

權限問題

# 使用用戶安裝
python3 -m pip install --user httpx fastmcp python-dotenv

# 或使用 homebrew Python
/opt/homebrew/bin/python3 -m pip install httpx fastmcp python-dotenv

調試模式

如果仍有問題，可以啟用調試模式：

{
  "mcpServers": {
    "thsrc": {
      "command": "npx",
      "args": ["-y", "@physictim/mcp-server-thsrc@latest"],
      "env": {
        "DEBUG_PYTHON_DETECTION": "1",
        "TDX_CLIENT_ID": "你的 Client ID",
        "TDX_CLIENT_SECRET": "你的 Client Secret"
      }
    }
  }
}

這會在 Claude Desktop 的日誌中顯示詳細的 Python 偵測過程。

授權

本專案使用 MIT 授權條款。

相關連結

• TDX運輸資料流通服務平臺
• 台灣高鐵官網
• Model Context Protocol