Taiwan TDX transport

tdx-taiwan-mcp

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 cached, 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 and other clients

Add the server to the client's MCP configuration (for 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"
      }
    }
  }
}

Environment

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

Tools

YouBike and buses

Bus tools take a city (Taipei, NewTaipei, ...) or InterCity for 公路客運 / 國道客運 coaches.

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.

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