How do I use Koleo MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Koleo MCP Server Find connections from Krakow to Warsaw for tomorrow morning" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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.