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

支援車站

中文站名	英文站名	站點 ID
南港	Nangang	0990
台北	Taipei	1000
板橋	Banqiao	1010
桃園	Taoyuan	1020
新竹	Hsinchu	1030
苗栗	Miaoli	1035
台中	Taichung	1040
彰化	Changhua	1043
雲林	Yunlin	1047
嘉義	Chiayi	1050
台南	Tainan	1060
左營	Zuoying	1070

資源

thsr://stations

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

⚠️ 注意事項

⚠️ 重要提示

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

💡 使用建議

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

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

📄 許可證

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

🔗 相關連結

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