# mcp-server-public-transport

[![smithery badge](https://smithery.ai/badge/mirodn/mcp-server-public-transport)](https://smithery.ai/server/mirodn/mcp-server-public-transport)

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

<a href="https://glama.ai/mcp/servers/@mirodn/mcp-server-public-transport">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@mirodn/mcp-server-public-transport/badge" />
</a>

## About

mcp-server-public-transport is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction)-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](https://transportapi.com)             | ✅  |
| **Switzerland**       | [https://transport.opendata.ch](https://transport.opendata.ch)   | ✅     |
| **Belgium**           | [https://api.irail.be](https://api.irail.be)                      | ✅     |
| **Norway**            | [https://api.entur.io](https://api.entur.io)                     | ✅    |
| **Berlin/Brandenburg**| [https://v6.vbb.transport.rest](https://v6.vbb.transport.rest)   | ✅    |
| **Portugal** (Lisbon + Porto) | [https://api.transitous.org](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](https://transitous.org), a free MOTIS instance over ingested GTFS feeds. No API key required.

#### Attribution (Transitous)

Lisbon/Porto data is served by [Transitous](https://transitous.org), 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](https://transitous.org/sources/).

Follow the [Transitous usage policy](https://transitous.org/api/): modest request volume,
an identifying `User-Agent`, non-commercial / open-source use only.

## Setup

### Environment Variables

Set the following environment variables:

```plaintext
UK_TRANSPORT_APP_ID=your_uk_app_id
UK_TRANSPORT_API_KEY=your_uk_api_key
```

### Usage with Claude Desktop

Add to your claude_desktop_config.json`:

```json
{
  "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**

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

2. **Install dependencies**

    ```bash
    uv sync
    ```

3. **Set environment variables**

    ```bash
    cp .env.example .env
    ```

4. **Run the server**

    ```bash
    uv run server.py
    ```

### Running Tests

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

```bash
# Run all tests
make test
```

### Code Quality

```bash
# 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](LICENSE)