Skip to main content
Glama
README.md
# mvg-mcp

An MCP server for Munich public transport (MVG/MVV). It lets Claude (or any MCP client) look up live departures, plan routes and check disruptions.

> ⚠️ This server uses the **unofficial** JSON API behind www.mvg.de. It is not documented, may change without notice, and is not endorsed by MVG. Keep request rates low and respect the MVG terms of use. Use it for personal, non-commercial purposes only.

## Tools

| Tool | What it does |
|---|---|
| `find_station(query)` | Search stations by name and get their global ids (`de:09162:2`) |
| `nearby_stations(latitude, longitude)` | Find the stations closest to a coordinate |
| `departures(station, limit, offset_minutes, transport_types)` | Live departures, including delays, platforms and cancellations |
| `plan_route(origin, destination, time, arrive_by, transport_types)` | Connections between two stations |
| `disruptions(line)` | Current service messages, optionally filtered by line (`U3`, `S8`, …) |

Wherever a tool takes a station, you can pass either a name (`"Marienplatz"`) or a global id. Times are in local time (Europe/Berlin). Transport type filters: `UBAHN, SBAHN, TRAM, BUS, REGIONAL_BUS, BAHN, SCHIFF`.

## Install

```bash
git clone <this repo> && cd mvg-mcp
uv sync            # or: pip install -e .
```

## Use with Claude Code

```bash
claude mcp add mvg -- uv run --directory /path/to/mvg-mcp mvg-mcp
```

## Use with Claude Desktop

In `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mvg": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mvg-mcp", "mvg-mcp"]
    }
  }
}
```

## Use with claude.ai / mobile (remote connector)

A remote connector needs a public HTTPS URL. Run the server over HTTP:

```bash
mvg-mcp --transport streamable-http --host 0.0.0.0 --port 8000
```

Then expose it, for example with a Cloudflare Tunnel or a small VPS behind a reverse proxy. Add `https://<your-host>/mcp` under **Settings → Connectors → Add custom connector**. The server has no authentication, so don't leave the URL publicly open long term.

## Development

```bash
pip install -e ".[dev]"
pytest
```

The tests mock the MVG API with `respx`. To smoke-test against the live API:

```bash
python -c "import asyncio; from mvg_mcp.client import MvgClient; c=MvgClient(); print(asyncio.run(c.find_stations('Marienplatz')))"
```