Koleo MCP Server

Local setup required. This server has to be cloned and prepared on your machine before you register it in Claude Code.
1

Set the server up locally

Run this once to clone and prepare the server before adding it to Claude Code.

Run in terminal
git clone https://github.com/MBratkowski/koleo-mcp.git
cd koleo-mcp
python3 -m pip install -e .
2

Register it in Claude Code

After the local setup is done, run this command to point Claude Code at the built server.

Run in terminal
claude mcp add koleo-mcp -- python3 "<FULL_PATH_TO_KOLEO_MCP>/dist/index.js"

Replace <FULL_PATH_TO_KOLEO_MCP>/dist/index.js with the actual folder you prepared in step 1.

README.md

MCP server for the Koleo Polish train timetable API.

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.

Tools (14)

tool_search_stationsSearch stations by name
tool_get_station_infoStation address, opening hours, facilities
tool_get_departuresDepartures from a station
tool_get_arrivalsArrivals at a station
tool_get_all_trainsAll trains (departures + arrivals) at a station
tool_search_connectionsFind connections A->B
tool_get_train_routeTrain route by brand + number
tool_get_train_by_idTrain route by Koleo train ID
tool_get_train_calendarOperating dates for a train
tool_get_realtime_timetableLive timetable (auth required)
tool_get_seat_statsSeat occupancy stats on a route
tool_get_seat_availabilityRaw seat map by connection ID
tool_get_brandsList train brands
tool_get_carriersList carriers

Environment Variables

KOLEO_MCP_CONFIGPath to the configuration file containing email and password for realtime data

Configuration

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

Try it

→Find train connections from Krakow to Warszawa for the next 3 departures.
→What are the facilities and opening hours for the Krakow Glowny station?
→Check the real-time status for train ID 12345.
→Show me the seat occupancy statistics for the connection between Krakow and Warszawa.
→List all available train brands operating in Poland.

Frequently Asked Questions

What are the key features of Koleo MCP Server?

Search for Polish train stations by name. Retrieve real-time departure and arrival schedules. Find train connections between two cities. Access detailed train routes and operating calendars. View seat occupancy statistics and availability.

What can I use Koleo MCP Server for?

Planning travel itineraries within Poland using natural language queries. Checking live train status and potential delays for upcoming trips. Analyzing station facilities and services before arriving at a train station. Monitoring seat occupancy trends for specific train routes.

How do I install Koleo MCP Server?

Install Koleo MCP Server by running: git clone https://github.com/MBratkowski/koleo-mcp.git && cd koleo-mcp && python3 -m pip install -e .

What MCP clients work with Koleo MCP Server?

Koleo MCP Server works with any MCP-compatible client including Claude Desktop, Claude Code, Cursor, and other editors with MCP support.

Turn this server into reusable context

Keep Koleo MCP Server docs, env vars, and workflow notes in Conare so your agent carries them across sessions.

Need the old visual installer? Open Conare IDE.
Open Conare
View all other servers →

Related MCP Servers

Nuclear
Free, open-source music player without ads or tracking.
other17.1K stars
Domain Check
Fast domain availability checker with RDAP/WHOIS lookup and batch checking.
other253 stars
US Government Open Data MCP
MCP Server + TypeScript SDK for 40+ U.S. Government APIs
other90 stars
Garmin Connect
Access your fitness, health, and training data from MCP clients.
other71 stars
BinjaLattice MCP
Secure communication protocol for Binary Ninja and MCP servers
other61 stars
Ghidra Headless MCP
Headless Ghidra server for AI-driven reverse engineering and analysis
other46 stars