mcp-server-public-transport

An MCP Server providing real-time public transport data across Europe.

About

mcp-server-public-transport is a Model Context Protocol (MCP)-compatible local server that provides access to public transport data across Europe. Currently, it integrates APIs from UK, Switzerland, Norway, Belgium, Berlin/Brandenburg and Portugal (Lisbon + Porto), allowing you to retrieve train connections, live departures, and bus locations.

Feature Implementation Status

Supported Countries

Country	API Base URL	Status
United Kingdom	https://transportapi.com	✅
Switzerland	https://transport.opendata.ch	✅
Belgium	https://api.irail.be	✅
Norway	https://api.entur.io	✅
Berlin/Brandenburg	https://v6.vbb.transport.rest	✅
Portugal (Lisbon + Porto)	https://api.transitous.org	✅

Features by Country

Feature	API Path	Status
United Kingdom
Live Departures	/uk/train/station_timetables/{station_code}.json	✅
Switzerland
Search Connections	/connections	✅
Station Lookup	/locations	✅
Departure Board	/stationboard	✅
Nearby Stations	/locations?x={lon}&y={lat}	✅
Belgium
Live Departures	/departures	✅
Station Lookup	/stations	✅
Nearby Stations	/stations/nearby	✅
Norway
Place Search	/geocoder/v1/autocomplete	✅
Live Departures	GraphQL: stopPlace(id) { estimatedCalls(...) }	✅
Trip Planning	GraphQL: trip(from, to, dateTime, numTripPatterns, ...)	✅
Nearest Stops	GraphQL: nearest(latitude, longitude, maximumDistance, ...)	✅
Berlin/Brandenburg
Location Search	/locations	✅
Live Departures	/stops/:id/departures	✅
Live Arrivals	/stops/:id/arrivals	✅
Journey Planning	/journeys	✅
Nearby Stations	/locations/nearby	✅
Portugal (Lisbon + Porto)
Station Lookup	/geocode	✅
Search Connections	/plan	✅
Departure Board	/stoptimes	✅
Nearby Stations	/reverse-geocode	✅

Portugal coverage is scoped to the Lisbon and Porto metro areas (Metro Lisboa, Carris, Carris Metropolitana, CP suburban; Metro do Porto, STCP) via Transitous, a free MOTIS instance over ingested GTFS feeds. No API key required.

Attribution (Transitous)

Lisbon/Porto data is served by Transitous, a volunteer-run, best-effort service (limited hosting, no availability or accuracy guarantees). Keep the Transitous attribution visible when showing this data to users; underlying feeds, including OpenStreetMap, are listed at transitous.org/sources.

Follow the Transitous usage policy: modest request volume, an identifying User-Agent, non-commercial / open-source use only.

Response Format

Departure/arrival boards and connection searches return a compact format that is the same for every country, instead of the raw upstream payload (typically 80–95% smaller):

{
  "station": {"id": "8503000", "name": "Zürich HB"},
  "departures": [
    {"line": "S 14", "category": "S", "destination": "Hinwil",
     "planned": "2026-10-05T10:12:00+02:00", "expected": "2026-10-05T10:36:00+02:00",
     "delay_min": 24, "platform": "33", "operator": "SBB"}
  ]
}

• Times are ISO 8601 in local time. expected is only set when real-time data exists.
• Journeys contain legs (with walk: true for footpaths); departure, arrival and duration_min of a journey are scheduled values, real-time data is on the legs.
• Disruption messages appear in remarks. Empty fields are omitted.
• Pass raw: true to get the unmodified upstream response.

Station searches, nearby lookups, be_get_vehicle and uk_live_departures still return the upstream payload.

Setup

Environment Variables

Set the following environment variables:

UK_TRANSPORT_APP_ID=your_uk_app_id
UK_TRANSPORT_API_KEY=your_uk_api_key

Usage with Claude Desktop

The quickest way is to run the published package with uvx (no clone needed). Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-server-public-transport": {
      "command": "uvx",
      "args": ["mcp-server-public-transport"],
      "env": {
        "UK_TRANSPORT_APP_ID": "your-uk-app-id",
        "UK_TRANSPORT_API_KEY": "your-uk-api-key"
      }
    }
  }
}

To run from a local clone instead:

{
  "mcpServers": {
    "mcp-server-public-transport": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/mcp-server-public-transport",
        "run",
        "server.py"
      ],
      "env": {
        "UK_TRANSPORT_APP_ID": "your-uk-app-id",
        "UK_TRANSPORT_API_KEY": "your-uk-api-key"
      }
    }
  }
}

Replace /ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-server-public-transport with the actual path where you've cloned the repository.

Note: You may need to put the full path to the uv executable in the command field. You can get this by running which uv on MacOS/Linux or where uv on Windows.

Development

Setting up Development Environment

1. Clone the repository

   git clone https://github.com/mirodn/mcp-server-public-transport.git
   cd mcp-server-public-transport
   

2. Install dependencies

   uv sync
   

3. Set environment variables

   cp env.example .env
   

4. Run the server

   uv run server.py
   

Running Tests

The project uses pytest for testing with the following commands available:

# Run all tests
make test

Code Quality

# Run linting
make lint

# Run code formatting
make format

Continuous Integration

The project includes a GitHub Actions workflow (.github/workflows/test.yml) that automatically:

• Runs tests on Python 3.10, 3.11, and 3.12
• Executes linting checks using ruff
• Runs on every push and pull request to main branch

The CI pipeline ensures code quality and compatibility across supported Python versions before any changes are merged.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

The package is deployed automatically to PyPI when project.version is updated in pyproject.toml. Follow semver for versioning.

License

MIT License