Thsrc MCP

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

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

🚀 快速開始

方法 1：使用 npx（推薦）

直接使用，不需要安裝：

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

方法 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

✨ 主要特性

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

📦 安裝指南

方法 1：使用 pipx（推薦）

# 安裝 pipx（如果還沒有）
python -m pip install --user pipx
python -m pipx ensurepath

# 安裝 MCP 服務器
pipx install git+https://github.com/yourusername/mcp-server-thsrc.git

方法 2：直接使用 pip

pip install git+https://github.com/yourusername/mcp-server-thsrc.git

方法 3：手動安裝

git clone https://github.com/yourusername/mcp-server-thsrc.git
cd mcp-server-thsrc
pip install -e .

🔧 環境設定

1. 註冊 TDX 帳號：前往 TDX 運輸資料流通服務平臺
2. 取得 API 金鑰（Client ID 和 Client Secret）

🔛 啟動服務

python thsrc.py

💻 使用示例

基礎用法

查詢臺北到左營的班次

# 使用中文站名
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")

高級用法

車站列表查詢

get_thsr_stations()

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

時刻表查詢

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

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

參數說明：

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

即時班次查詢

get_thsr_live_schedule("臺北")

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

參數說明：

• station：車站名稱或 ID

特定班次資訊

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

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

參數說明：

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

剩餘座位查詢

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

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

參數說明：

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

更新頻率：

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

📚 詳細文檔

整合到 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（推薦）：

{
  "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 工具來取得即時資料。

支援車站

資源

thsr://stations

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

⚠️ 注意事項

⚠️ 重要提示

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

💡 使用建議

遇到問題時，可根據錯誤類型進行排查：

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

📄 許可證

本專案使用 MIT 許可證條款。

🔗 相關連結

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