IDOS MCP Server

Lets AI assistants look up Czech public transport on IDOS.cz: journeys from A to B, departure and arrival boards with platforms and live delays, the route of a train by its number, and city-line timetables for Prague, Brno and about 90 other cities.

It is read-only. It can't buy tickets, make reservations, log in or create an account.

Installation

Prerequisites

Node.js 20.3 or newer. The Claude Desktop extension doesn't need it, because Claude Desktop includes its own.

No account, API key or other setup is needed. The server runs locally and reads the public IDOS website.

Claude Code

claude mcp add idos -- npx -y idos-mcp-server

Claude Desktop

Download idos-mcp-server.mcpb and open it. Claude Desktop shows an install screen; there is nothing to fill in.

Open Settings → Developer → Edit Config, add the server to claude_desktop_config.json, then restart Claude Desktop:

{
  "mcpServers": {
    "idos": {
      "command": "npx",
      "args": ["-y", "idos-mcp-server"]
    }
  }
}

VS Code

Use the install button above, or add this to .vscode/mcp.json or your user MCP configuration:

{
  "servers": {
    "idos": {
      "command": "npx",
      "args": ["-y", "idos-mcp-server"]
    }
  }
}

Cursor

Use the install button above, or add this to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "idos": {
      "command": "npx",
      "args": ["-y", "idos-mcp-server"]
    }
  }
}

Other MCP hosts

Any host that supports local (stdio) MCP servers works. Configure it to run npx -y idos-mcp-server. Most hosts use the same JSON format as the Claude Desktop and Cursor examples above.

Build from source

Clone this repository and run npm install and npm run build. Then use node /path/to/idos-mcp-server/build/index.js as the command in your host's config instead of npx -y idos-mcp-server.

Check that it works

Ask your assistant: "When is the next train from Praha hl.n. to Brno?" It should list connections with times, platforms and changes.

Related MCP server: golemio-mcp

Tools

Every tool also takes response_format: markdown (default) or json (string, optional). Dates are YYYY-MM-DD or Czech D.M.YYYY, times are HH:MM; leaving them out means today and now.

• idos_search_locations - Find stations, stops and towns by (partial) name, with their type, region, transport modes and coordinates

  • query: Start of the name, e.g. Brno, Praha hl. Diacritics are optional (string, required)

  • limit: Maximum matches, 1–50, default 10 (number, optional)

  • only_stations: Only concrete stations and stops, not towns (boolean, optional)

  • timetable: Which timetables to search, see Timetables (string, optional)

• idos_search_connections - Plan a journey from A to B: departure and arrival times, changes, and each leg's train or line, carrier, platforms and delays

  • from, to: Start and destination, e.g. Praha, Brno hl.n.. A town means any stop in it (string, required unless page_token is given)

  • via: Up to 3 places to travel through (string[], optional)

  • date, time: When to travel (string, optional)

  • arrival: true makes time the latest arrival instead of the earliest departure (boolean, optional)

  • only_direct: Only connections without changes (boolean, optional)

  • max_changes: Maximum number of changes, 0–10 (number, optional)

  • count: How many connections to return, 1–15, default 5 (number, optional)

  • page_token: next_page_token or prev_page_token from a previous result, for later or earlier connections (string, optional)

  • timetable: Which timetables to search, see Timetables (string, optional)

• idos_get_connection_detail - Every stop of a connection with arrival and departure times, platforms and km, plus the carrier's notes

  • connection_id: connection_id from idos_search_connections, or an IDOS connection link (string, required)

  • include_full_route: Also show the stops outside your part of each trip (boolean, optional)

  • timetable: Which timetables to search (string, optional)

• idos_get_departures - A station's departures or arrivals with platforms, carriers and live delays

  • station: A station or stop, e.g. Praha hl.n., Florenc. If it's ambiguous, the error lists the exact names (string, required unless page_token is given)

  • direction: departures (default) or arrivals (string, optional)

  • date, time: When to start the board (string, optional)

  • line: Only this line, train or carrier, e.g. R9, IC 500, 207, Pendolino, Leo Express (string, optional)

  • destination: Only services going to (or, for arrivals, coming from) or through this place, e.g. Kolín (string, optional)

  • limit: Maximum entries, 1–100, default 20 (number, optional)

  • page_token: next_page_token from a previous result, for later entries (string, optional)

  • timetable: Which timetables to search (string, optional)

• idos_get_trip_route - Every stop of one trip from a board, with times, platforms, km, tariff zones and the live position

  • trip_id: trip_id of an entry from idos_get_departures (string, required)

• idos_get_train_route - Find a train or long-distance bus by number or name at a station it leaves from, and show its whole route

  • train: e.g. R 871, EC 171, 871, Pendolino (string, required)

  • station: A station where it departs, e.g. Praha hl.n. (string, required)

  • date (string, optional)

  • time: Roughly when it leaves that station. Much faster, and needed for trains late in the day at big stations (string, optional)

  • timetable: vlaky (trains, default), autobusy (long-distance buses) or vlakyautobusymhdvse (string, optional)

  • max_pages: How many board pages to scan, 1–15, default 6 (number, optional)

• idos_list_city_timetables - List the cities whose bus, tram, trolleybus and metro lines have stop timetables

• idos_search_lines - Find a city line and its route variants (first stop → last stop)

  • city: e.g. Praha (default), Brno, Ostrava, Plzeň (string, optional)

  • query: Line number, e.g. 136, 22, A (string, required)

  • date (string, optional)

  • limit: Maximum route variants, 1–50, default 20 (number, optional)

• idos_get_line_route - All stops of a city line in order, with travel minutes, tariff zones and stop attributes

  • city (string, optional)

  • line: e.g. 136, Tram 22 (string, required)

  • direction: Last stop of the route variant, e.g. Jižní Město. Defaults to the first variant (string, optional)

  • date (string, optional)

• idos_get_stop_timetable - The timetable of one line at one stop, by hour, for a date or the whole week

  • city (string, optional)

  • line (string, required)

  • stop: e.g. Flora (string, required)

  • direction: Any later stop on the line, usually the last one (string, optional)

  • date (string, optional)

  • whole_week: Workday, Saturday and Sunday tables instead of one date (boolean, optional)

Timetables

Most tools take a timetable that picks which IDOS timetables to search. The default, vlakyautobusymhdvse, covers all trains, buses and city transport. Others include vlaky (trains only), autobusy (long-distance buses), pid (Prague) and idsjmk (South Moravia).

Good to know

• No ticket prices. IDOS only shows prices through its ticket shop, which this server never opens.

• Paging re-runs the search. Results come with an opaque page_token for the next (or previous) page, and the server searches again from the last time shown.

• Names are checked first. Without that, IDOS quietly guesses, e.g. "Florenc" would become Florence in Italy. When a name is ambiguous, the tool lists the exact names to use.

• Czech text stays Czech. Notes, remarks and carrier information come straight from IDOS.

• Be gentle. Requests are spaced at least 250 ms apart. This server is meant for personal lookups, not bulk scraping.

• The website can change. IDOS has no public API, so the server reads its web pages. If CHAPS changes them, a tool may stop working until it's updated.

Troubleshooting

Found a bug or want a feature? Open an issue.

License

This project is licensed under the Apache 2.0 license.