微信扫一扫README
🚀 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 .
🔧 環境設定
- 註冊 TDX 帳號：前往 TDX 運輸資料流通服務平臺
- 取得 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 的應用程式中直接存取。
⚠️ 注意事項
⚠️ 重要提示
- 請遵守 TDX API 的使用限制
- 確保正確設定 TDX API 金鑰
- 日期必須使用 YYYY - MM - DD 格式
- 支援中英文站名，大小寫敏感
💡 使用建議
遇到問題時，可根據錯誤類型進行排查：
- 無效站名：會拋出
ValueError錯誤- API 認證失敗：請檢查環境變數設定
- 網路連線問題：請確認網路連線狀態
📄 許可證
本專案使用 MIT 許可證條款。