Taiwan TDX transport

tdx-taiwan-mcp

一个非官方的台湾 MCP 服务，适用于 TDX（Transport Data eXchange） API，基于 tdx-taiwan SDK 构建。它让 Claude 和其他 MCP 客户端能够回答诸如“最近的哪家 YouBike 还有车？”、“307 路什么时候到西门？”、“今晚开往左营的高铁还有哪些有座位？”、“CI100 是否延误？”或“台北车站附近哪里可以给 CCS2 汽车充电？”等问题。

• 面向任务的工具：按名称（中文或英文，会统一台／臺）或位置搜索，结果易读（“4 分钟”“末班车已开过”），而不是原始状态码
• 城市名称可使用 TDX 代码或中文（Taipei、臺北市、台北）
• 限制结果数量；静态列表会缓存，实时数据缓存 15 秒
• tdx_get 可访问工具尚未覆盖的任意 TDX 端点
• 通过 stdio 运行；需要 Node.js 20+

获取 TDX 密钥

在 tdx.transportdata.tw 注册，然后从 會員中心 → 資料服務 → API金鑰 复制 Client Id 和 Client Secret。

设置

Claude Code

claude mcp add tdx \
  -e TDX_CLIENT_ID=your-client-id -e TDX_CLIENT_SECRET=your-client-secret \
  -- npx -y tdx-taiwan-mcp

Claude Desktop 和其他客户端

将服务添加到客户端的 MCP 配置中（Claude Desktop 使用 claude_desktop_config.json）：

{
  "mcpServers": {
    "tdx": {
      "command": "npx",
      "args": ["-y", "tdx-taiwan-mcp"],
      "env": {
        "TDX_CLIENT_ID": "your-client-id",
        "TDX_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

环境变量

变量	默认值	含义
TDX_CLIENT_ID	required	TDX API 密钥 Client Id
TDX_CLIENT_SECRET	required	TDX API 密钥 Client Secret
TDX_REQUESTS_PER_SECOND	5	客户端速率限制；请设为与 TDX 套餐一致（0 表示关闭）
TDX_MAX_ITEMS	200	任意工具返回的最大条目数

也会读取工作目录中的 .env 文件；已设置的变量优先。

工具

YouBike 和公交车

工具	可回答的问题
youbike_nearby	查找坐标附近当前有车（或有空桩）的最近 YouBike／Moovo 站点
youbike_station	按名称或地址查找 YouBike 站点，并显示实时单车、电动自行车和空桩数量
bus_stops_nearby	查找坐标附近的公交站，并显示站点朝向以及经过的市区和公路客运路线
bus_stop_arrivals	查询某个站点所有路线即将到站的公交车，按到站时间从近到远排列
bus_route_search	按名称或终点站查找公交路线，并显示起讫点、运营商和票价
bus_route_stops	按方向和子路线，依次列出某条路线的站点
bus_eta	查询路线各站的实时到站预估，可选择指定站点
bus_timetable	查询某条路线某日的计划发车时间，或发车频率
bus_alerts	查询当前和即将实施的绕行、停驶和站点迁移信息，以及最新消息
bus_positions	查询某条路线上的公交车当前位置、速度和状态

公交工具接受城市名称（Taipei、NewTaipei 等），或使用 InterCity 查询公路客運／國道客運 客车。

铁路

工具	可查询的信息
thsr_timetable	某日两站之间的高铁列车
thsr_seats	这些列车的标准座和商务座余票
thsr_fare	高铁各车厢及乘客类型的票价
thsr_train	一趟高铁列车的所有停靠站
tra_timetable	两站之间的台铁列车及列车类型
tra_live_board	即将到达或离开台铁车站的列车及延误情况
tra_train	今日的一趟台铁列车：停靠站、当前位置及延误情况
tra_fare	台铁各列车类型及乘客类型的票价
metro_live_board	下一班捷运列车的到站时间（高雄、桃园；台北仅显示到站信息）
metro_fare	两站之间的捷运票价
metro_first_last_train	捷运车站的首班车和末班车
afr_timetable	阿里山林业铁路的常规时刻表
rail_station_search	按名称或距坐标最近的位置搜索任意铁路系统的车站
rail_alerts	高铁、台铁或捷运的服务状态及运行中断信息

铁路工具接受中文或英文车站名称（台北、Taipei、台北車站）或车站 ID。查询今日时，时刻表从台湾当地当前时间开始。

航班

工具	可查询的信息
flight_status	航班的时间、延误、登机口及状态（CI100）
flight_board	台湾机场的出发或到达航班信息，以及当前天气
flight_schedule	某日台湾两座机场之间的国内航班（华信、立荣、德安）及票价

机场可使用 IATA 代码或名称（TSA、松山、Kinmen）。

渡轮

工具	可查询的信息
ferry_timetable	某日两港之间的航班、实时状态及今日警报（台风）
ferry_live_board	港口今日的出发和到达航班、延误及取消情况
ferry_fare	两港之间按票种、舱位及乘客类型划分的票价
ferry_alerts	当前渡轮服务的停航及变更信息

港口可使用名称（富岡、綠島、小琉球）或港口 ID。由县市运营的航线（澎湖 离岛船、旗津、淡水）需要提供 city，例如 PenghuCounty。

道路

工具	可查询内容
traffic_live	各路段的实时车速和拥堵情况，按最严重程度排序，并统计各级别数量
traffic_travel_time	根据实时 eTag 数据，查询当前两处高速公路交流道之间的汽车行程时间，细分至各路段
traffic_events	事故、道路施工、封闭和已公告的活动（游行）及其地点

道路工具需要指定路网：freeway（國道）、highway（省道）或城市；traffic_travel_time 需要使用中文填写高速公路交流道名称（林口、新竹）。高速公路路段以交流道命名，因此 可按关键词搜索（林口）。

停车和电动汽车充电

工具	可查询内容
parking_nearby	最近的停车场和路边停车位，以及当前空余的汽车或机车车位
parking_search	按名称、地址或道路查询停车场和路边停车位，以及空余车位
ev_charger_nearby	最近的电动汽车充电桩，包含空闲充电接口（CCS2、Tesla 等）、交流或直流充电及价格

各城市的数据覆盖范围不同：NewTaipei 仅提供路边停车位，且并非每个停车场都会发布实时空位 （这类停车场会显示“无实时数据”）。ev_charger_nearby 的 freeway 参数用于查询 高速公路服务区。

其他

工具	可查询内容
tdx_get	任意 TDX API 路径，支持 OData filter、select、orderBy、top、skip

MCP 注册表

该服务已列入 MCP 注册表，名称为 io.github.amangeldievkuu/tdx-taiwan-mcp，因此可浏览注册表的客户端能够使用上文提到的两个 TDX 变量安装它。

作为库使用

import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { TdxClient } from 'tdx-taiwan';
import { createServer } from 'tdx-taiwan-mcp';

const tdx = new TdxClient({ clientId: '…', clientSecret: '…', cache: true });
await createServer({ tdx }).connect(new StdioServerTransport());

速率限制和计费

TDX 会根据套餐限制每秒请求数，并按调用次数和响应大小计费。服务会缓存静态列表（车站、路线） 一小时，实时数据缓存 15 秒，并按照 TDX_REQUESTS_PER_SECOND 间隔发送请求。如果 TDX 仍返回 429（基础套餐也会限制每分钟的调用次数），服务会按照 TDX 的要求等待并重试，因此问题集中 出现时，一次工具调用可能需要一分钟。

数据来源

資料來源：交通部 TDX 運輸資料流通服務平臺 (MOTC Transport Data eXchange). TDX 数据受 TDX 資料授權利用條款约束。本项目与 MOTC 或 TDX 无关联。

许可证

MIT