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

Related MCP server: mcp-national-rail

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

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.