Mvg Stoerung

A Model Context Protocol (MCP) server that provides cached access to Munich Public Transport (MVG) disruption data.

Features

• Cached Data: Automatically caches MVG incident data for at least 10 minutes to reduce API calls
• Real-time Incidents: Fetches current incidents from the official MVG API
• Search Functionality: Search incidents by line, title, or description
• Enhanced Data: Adds human-readable timestamps and formats data for easy consumption
• MCP Compatible: Works with any MCP-compatible client

Data Source

This server uses the official MVG API endpoint: https://www.mvg.de/api/bgw-pt/v3/messages

The server filters the API response to only return incidents (type=INCIDENT) and enhances the data with:

• Human-readable timestamps
• Formatted descriptions
• Deduplicated line information

Installation

# Install dependencies
pip install -r requirements.txt

# Or install as a package
pip install -e .

Usage

Running the Server

python mvg_mcp_server.py

Available Tools

1. get_mvg_incidents: Get current MVG incidents (cached for 10+ minutes)

   • Optional parameter: force_refresh (boolean) - Force refresh cache even if not expired

2. get_cache_status: Get information about the cache status

3. search_incidents: Search incidents by line, title, or description

   • Required parameter: query (string) - Search query
   • Optional parameter: line (string) - Filter by specific line (e.g., 'U6', 'S1')

Available Resources

1. mvg://incidents: Current incidents from Munich Public Transport (MVG)
2. mvg://cache-info: Information about the current cache status

Example Usage

Get All Current Incidents

{
  "method": "tools/call",
  "params": {
    "name": "get_mvg_incidents"
  }
}

Search for U6 Line Issues

{
  "method": "tools/call",
  "params": {
    "name": "search_incidents",
    "arguments": {
      "query": "verspätung",
      "line": "U6"
    }
  }
}

Force Cache Refresh

{
  "method": "tools/call",
  "params": {
    "name": "get_mvg_incidents",
    "arguments": {
      "force_refresh": true
    }
  }
}

Cache Behavior

• Cache Duration: 10 minutes minimum (configurable)
• Automatic Refresh: Cache is automatically refreshed when expired
• Force Refresh: Can be manually triggered via the force_refresh parameter
• Cache Info: View cache status including expiration time and cached item count

Data Format

Each incident includes:

• title: Incident title
• description: Detailed description
• type: Always "INCIDENT"
• publication: Publication timestamp (Unix milliseconds)
• publication_readable: Human-readable publication time
• validFrom/validTo: Validity period
• validFrom_readable/validTo_readable: Human-readable validity times
• lines: Affected transport lines with details
• provider: Always "MVG"

Error Handling

The server handles various error conditions:

• API timeouts and connection errors
• Invalid JSON responses
• Cache expiration
• Missing or malformed data

Development

Project Structure

├── mvg_mcp_server.py    # Main MCP server implementation
├── requirements.txt     # Python dependencies
├── pyproject.toml      # Project configuration
└── README.md           # This file

Dependencies

• mcp>=1.0.0: Model Context Protocol framework
• httpx>=0.25.0: Async HTTP client
• pydantic>=2.0.0: Data validation and serialization

License

This project is dedicated to the public domain under the CC0 1.0 Universal license. See the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Disclaimer

This project is not an official MVG project, not endorsed or recommended. Please ask MVG for permission prior to using it.