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:

1. tool_search_stations with:
   • query: Krakow
2. tool_get_departures with:
   • station: Krakow Glowny
3. tool_search_connections with:
   • start: Krakow
   • end: Warszawa
   • length: 3
4. tool_get_brands
5. 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.