Taiwan TDX transport

tdx-taiwan-mcp

[npm] [CI] [license]

繁體中文說明

An unofficial MCP server for Taiwan's TDX (Transport Data eXchange) API, built on the tdx-taiwan SDK. It lets Claude and other MCP clients answer questions such as "where is the nearest YouBike with bikes?", "when does the 307 reach Ximen?", "which high speed trains to Zuoying still have seats tonight?", "is CI100 delayed?" or "where can I charge a CCS2 car near Taipei Main Station?".

• Task-shaped tools: search by name (Chinese or English, 台/臺 folded) or by location, with readable output ("4 min", "last bus has passed") instead of raw status codes
• City names as TDX codes or in Chinese (Taipei, 臺北市, 台北)
• Results capped in size; static lists kept on disk for a day, live data cached for 15 s
• tdx_get for any TDX endpoint the tools do not cover yet
• Runs over stdio; Node.js 20+

Get TDX keys

Register at tdx.transportdata.tw, then copy the Client Id and Client Secret from 會員中心 → 資料服務 → API金鑰.

Set up

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

Download tdx-taiwan-mcp-<version>.mcpb from the latest release and open it (or drag it into Settings → Extensions). Claude Desktop asks for your TDX Client Id and Secret, stores the secret in the system keychain, and runs the server with its own Node.js. The settings also take the tool groups to load (see TDX_TOOLS below).

Other clients

Add the server to the client's MCP configuration (or Claude Desktop's claude_desktop_config.json, instead of the extension):

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

Environment

A .env file in the working directory is read too; variables already set take precedence.

Disk cache. Station, route and timetable lists are kept on disk for a day, so a new session answers from them instead of calling TDX again. A first metro journey that took close to two minutes on the free plan's per-minute quota then takes a fraction of a second. The default folder is ~/.cache/tdx-taiwan-mcp ($XDG_CACHE_HOME if set; %LOCALAPPDATA% on Windows), a few MB at most. Live data (arrivals, availability, positions) is never stored.

Loading fewer tools. Every tool's description goes into the model's context, and with 47 of them a model can pick the wrong one. If you only need some areas, list them in TDX_TOOLS: bike, bus, rail (THSR, TRA, metro, Alishan), flight, ferry, road, parking, ev and raw (tdx_get). A list loads only those groups (bus,rail); names with a minus leave groups out of all of them (-road,-raw). The server's instructions to the model cover only the loaded groups.

Tools

YouBike, cycling and buses

Bus tools take a city (Taipei, NewTaipei, ...) or InterCity for 公路客運 / 國道客運 coaches. Whether a bus is low-floor with a wheelchair ramp comes from the fleet lists that Taipei, New Taipei, Taoyuan, Taichung, Tainan and Kaohsiung publish; Taipei and New Taipei do not say which bus an arrival estimate is for, so bus_eta estimates it from where each bus last stopped.

Rail

Rail tools take station names in Chinese or English (台北, Taipei, 台北車站) or station IDs. For today, timetables start from the current time in Taiwan.

Flights

Airports are IATA codes or names (TSA, 松山, Kinmen).

Ferries

Ports are names (富岡, 綠島, 小琉球) or port IDs. Lines run by a county (Penghu inter-island boats, 旗津, 淡水) need city, e.g. PenghuCounty.

Roads

Road tools take a network: freeway (國道), highway (省道) or a city; traffic_travel_time takes freeway interchange names in Chinese (林口, 新竹). Freeway sections are named after interchanges, so search them by keyword (林口).

Parking and EV charging

Coverage differs per city: NewTaipei has on-street parking only, and not every car park publishes live spaces (those show "no live data"). ev_charger_nearby takes freeway for the freeway service areas.

Other

MCP registry

The server is listed in the MCP registry as io.github.amangeldievkuu/tdx-taiwan-mcp, so clients that browse the registry can install it with the two TDX variables above.

Use as a library

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());

Rate limits and billing

TDX limits requests per second by plan and bills by call count and response size. The server caches static lists (stations, routes) for an hour and live data for 15 seconds, and spaces requests at TDX_REQUESTS_PER_SECOND. When TDX still answers 429 (the basic plan also limits calls per minute), the server waits as TDX asks and retries, so a tool call can take up to a minute during a burst of questions.

繁體中文

tdx-taiwan-mcp 是交通部 TDX 運輸資料流通服務的非官方 MCP 伺服器（與交通部無隸屬或合作關係），讓 Claude 等 MCP 用戶端以即時資料回答「最近哪個 YouBike 站有車？」「307 公車幾分鐘到西門？」「今晚往左營的高鐵還有座位嗎？」「CI100 有沒有誤點？」等問題，涵蓋 YouBike 與自行車道、市區公車與公路客運（含票價與首末班車）、高鐵、臺鐵、捷運、阿里山林業鐵路、國內外航班、船運、即時路況與路況影像、停車場及充電樁。

取得金鑰：註冊 TDX 會員後，至「會員中心 → 資料服務 → API金鑰」取得 Client Id 與 Client Secret。

安裝

• Claude Desktop：從最新版本下載 tdx-taiwan-mcp-<版本>.mcpb 並開啟，依提示填入 Client Id 與 Client Secret（密鑰存於系統鑰匙圈）。

• Claude Code：

  sh

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

• 其他用戶端：以 npx -y tdx-taiwan-mcp 啟動，並設定上述兩個環境變數（需要 Node.js 20 以上版本）。

設定（環境變數）

• TDX_TOOLS：只載入部分工具群組，例如 bus,rail；加上減號可排除，例如 -road,-raw。群組有 bike、bus、rail（高鐵、臺鐵、捷運、阿里山）、flight、ferry、road、parking、ev 與 raw（tdx_get）。工具愈少，模型愈容易選對工具。
• TDX_CACHE_DIR：站點、路線、時刻表等靜態資料會在磁碟保存一天（預設 ~/.cache/tdx-taiwan-mcp），新的工作階段不必再向 TDX 下載；設為 off 可關閉。即時資料不會存檔。
• TDX_REQUESTS_PER_SECOND：用戶端限流，預設每秒 5 次，請依您的 TDX 方案調整。TDX_MAX_ITEMS：每個工具最多回傳的筆數，預設 200。

使用提示：站名、港口與機場可用中文或英文（台北、Taipei、松山、TSA）；城市可用 TDX 代碼或中文（Taipei、臺北市）；時間皆為臺灣時間（UTC+8）。公車工具需要完整路線名稱，可先用 bus_route_search 查詢；bus_eta 與 bus_positions 會標示公車是否為低地板、有無輪椅斜坡（依各縣市公布的車輛資料）。

Data source

資料來源：交通部 TDX 運輸資料流通服務平臺 (MOTC Transport Data eXchange). TDX data is subject to the TDX 資料授權利用條款. This project is not affiliated with MOTC or TDX.

License

MIT