koleo-mcp

MCP server for the Koleo Polish train timetable API.

It exposes 14 tools you can call from Claude Desktop (or any MCP client) to search stations, departures/arrivals, connections, train routes, seat data, and realtime timetable.

Requirements

Python 3.12+
pip

Quick start (copy/paste)

git clone https://github.com/MBratkowski/koleo-mcp.git
cd koleo-mcp
python3 -m pip install -e .
python3 server.py

If server.py starts without crashing, the server is ready.

How to test the server (easy mode)

Run the MCP inspector:

mcp dev server.py

Then in the inspector UI call these tools:

tool_search_stations with:
- query: Krakow
tool_get_departures with:
- station: Krakow Glowny
tool_search_connections with:
- start: Krakow
- end: Warszawa
- length: 3
tool_get_brands
tool_get_realtime_timetable with:
- train_id: any integer (for example 12345)

Each tool returns JSON with at least:

data
summary
koleo_url

On errors you also get an error key.

How to use with Claude Desktop

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "koleo": {
      "command": "python3",
      "args": ["/absolute/path/to/koleo-mcp/server.py"]
    }
  }
}

Replace /absolute/path/to/koleo-mcp/server.py with your real path.

Restart Claude Desktop.

Authentication (optional, needed for realtime tool)

Create ~/.config/koleo-mcp/config.json:

{
  "email": "your@email.com",
  "password": "yourpassword"
}

You can override the config path with KOLEO_MCP_CONFIG.

If auth is missing, tool_get_realtime_timetable returns a friendly auth_required error.

Available tools

Tool	Description
`tool_search_stations`	Search stations by name
`tool_get_station_info`	Station address, opening hours, facilities
`tool_get_departures`	Departures from a station
`tool_get_arrivals`	Arrivals at a station
`tool_get_all_trains`	All trains (departures + arrivals) at a station
`tool_search_connections`	Find connections A->B
`tool_get_train_route`	Train route by brand + number
`tool_get_train_by_id`	Train route by Koleo train ID
`tool_get_train_calendar`	Operating dates for a train
`tool_get_realtime_timetable`	Live timetable (auth required)
`tool_get_seat_stats`	Seat occupancy stats on a route
`tool_get_seat_availability`	Raw seat map by connection ID
`tool_get_brands`	List train brands
`tool_get_carriers`	List carriers

Troubleshooting

ModuleNotFoundError: run python3 -m pip install -e . again.
SSL certificate errors on macOS/Python.org builds: install certificates for your Python installation and retry.
auth_required for realtime tool: add ~/.config/koleo-mcp/config.json as shown above.

Koleo MCP Server