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.
expectedis only set when real-time data exists. - Journeys contain
legs(withwalk: truefor footpaths);departure,arrivalandduration_minof a journey are scheduled values, real-time data is on the legs. - Disruption messages appear in
remarks. Empty fields are omitted. - Pass
raw: trueto get the unmodified upstream response.
Station searches, nearby lookups, be_get_vehicle and uk_live_departures still return
the upstream payload.
Setup
Hosted Server (no install)
A public instance is available via Streamable HTTP:
https://mcp-public-transport-412652413053.europe-west1.run.app/mcp
- Claude (web / desktop): Settings → Connectors → Add custom connector, paste the URL.
- Claude Code:
claude mcp add --transport http public-transport https://mcp-public-transport-412652413053.europe-west1.run.app/mcp
The hosted instance does not include UK tools. For UK data, run the server locally with your own keys (see below).
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
-
Clone the repository
git clone https://github.com/mirodn/mcp-server-public-transport.git cd mcp-server-public-transport
-
Install dependencies
uv sync -
Set environment variables
cp env.example .env
-
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
mainbranch
The CI pipeline ensures code quality and compatibility across supported Python versions before any changes are merged.
Hosting (Google Cloud Run)
The hosted instance runs on Cloud Run with stateless Streamable HTTP (MCP_STATELESS=true),
scale-to-zero and a single max instance. A monthly budget triggers
deploy/budget-guard, which makes the service private
once the budget is used up.
The hosted instance has no UK credentials, so UK tools are not available there. To use them, get your own key at transportapi.com and run the server locally (see Setup).
- One-time setup:
deploy/gcp-setup.sh - Deploys:
.github/workflows/deploy-cloudrun.ymlruns on release tags or manually. It only swaps the image, so limits and public access stay as configured.
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
Metadata
Release files for mcp-server-public-transport 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mcp_server_public_transport-0.3.0.tar.gz | 37.8 kB | Without provenance | Details for mcp_server_public_transport-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mcp_server_public_transport-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for mcp_server_public_transport-0.3.0-py3-none-any.whl |
Total release size: 70.9 kB
Release files / mcp_server_public_transport-0.3.0.tar.gz
| Download URL | mcp_server_public_transport-0.3.0.tar.gz |
|---|---|
| Size | 37.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ec4b97d340aa0854ab44f79e4e518679c0aac1a89bec3c46eb434d3fcb3df9f1
|
|
BLAKE2b-256 checksum How to use checksums |
4ec2ff8bd8b37bdfc197c40d772da9058dad538542e02a953086a9d5a67ef2d1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.17
|
Release files / mcp_server_public_transport-0.3.0-py3-none-any.whl
| Download URL | mcp_server_public_transport-0.3.0-py3-none-any.whl |
|---|---|
| Size | 33.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
eeec6171b12f6913cfe54fc0fb877ad841f350935cc1ad2a6b6c55a37b9a6c74
|
|
BLAKE2b-256 checksum How to use checksums |
f077451c541b699c2cf899ed3bd10f25d0777cfaf111e9c04fa21f30a9838261
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.17
|
Security for mcp-server-public-transport 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.