12306-skill

This Skill addresses the cumbersome process of applying for API keys when querying China Railway 12306 train schedules and ticket availability. In practical travel planning, users often need to quickly obtain train numbers, departure times, arrival times, and seat availability for a specific route. However, official channels or third-party APIs typically require registration, authentication, or even payment, making the process lengthy.

Usage is straightforward: simply run a command in the terminal with the departure station, destination, and optional parameters. For example, to query all trains from Beijing to Shanghai for today, execute node {baseDir}/scripts/query.mjs Beijing Shanghai. This generates an HTML file displaying the results. To output a Markdown table for easy sharing in chats, add the -f md flag. It also supports flexible filtering by train type (G/D/Z/T/K), departure time range, arrival time range, maximum travel duration, and showing only trains with available tickets.

It is ideal for individuals or teams who frequently need to query train ticket information, especially those who have integrated AI coding assistants (like Claude or Cursor) into their workflows. University students, job seekers, and frequent business travelers can use natural language instructions to have an AI agent directly invoke this tool, eliminating the need to manually open a browser or app. For data analysts, the JSON output mode enables batch data retrieval for further analysis.

Before querying, it is recommended to use the stations.mjs script to confirm the full station name, as a single city may have multiple stations (e.g., Wuhan Station, Hankou Station, Wuchang Station). Entering just the city name may lead to inaccurate results. Please note that this tool relies on a Node.js environment, and query results are based on 12306's public data, which may be affected by network restrictions or anti-crawling mechanisms. It is advisable to control query frequency appropriately.