This MCP server provides five tools to access SBB timetable data through a language-model-friendly interface: nextJourney, planJourney, listJourneys, listAndPlanJourneys, and raw, plus a small helper datum that returns today’s date in ISO format. The nextJourney tool returns a natural-language description of the next available connection between two stations (for now/soon scenarios). planJourney returns the next connection after a specified ISO datetime (e.g., today at 14:35). listJourneys provides several upcoming connections for today as JSON, while listAndPlanJourneys returns multiple connections starting from a given datetime as JSON (useful for “show me trains after 16:00”). The raw tool exposes the unprocessed JSON response from the SBB Journey Service for debugging or advanced analysis. Use datum to obtain today’s date in ISO format for precise date resolution. To use, call the MCP server’s tools through your MCP client interface, selecting the appropriate function based on user intent and the required time context, and parse the structured JSON (or the natural-language description) returned by each tool.

Prerequisites:

• Java 21 or newer installed on the host
• Git and a Java build tool (Maven or Gradle) available
• Access to the SBB Journey API with valid credentials (via JOURNEY_SERVICE_BASE, JOURNEY_SERVICE_CLIENT_ID, JOURNEY_SERVICE_CLIENT_SECRET)

Install steps:

1. Clone the repository: git clone https://github.com/thpeng/chattender-fahrplan-mcp.git cd chattender-fahrplan-mcp

2. Build the project (using Maven): ./mvnw -B clean package

   or with Maven installed: mvn -B clean package

3. Verify the build artifact exists, e.g.: ls build/libs/

   you should see something like chattender-fahrplan-0.0.1.jar

4. Configure environment variables (as described in mcp_config):

   • JOURNEY_SERVICE_BASE
   • MCP_API_KEY
   • JOURNEY_SERVICE_CLIENT_ID
   • JOURNEY_SERVICE_CLIENT_SECRET

5. Run the MCP server: java -jar build/libs/chattender-fahrplan-0.0.1.jar

6. Optional: run with Spring Boot specifics or via your preferred deployment method (e.g., systemd, Docker, or cloud Run) and ensure the environment variables are provided in the deployment environment.

Tips and considerations:

• The server exposes multiple tools that query the SBB Journey API; beware that the raw tool can produce very large JSON payloads which may overwhelm limited-context models.
• Ensure all environment variables are correctly set; missing API keys or base URLs will prevent tool calls from succeeding.
• Time-zone handling can vary between the MCP host and the SBB API. Use datum to resolve the current date when composing planJourney and listJourneys requests.
• The API may return edge cases or delayed trains; consider using nextJourney or planJourney with careful time context to minimize ambiguity.
• For debugging, the raw tool can be invaluable but use it judiciously due to payload size.
• If you are deploying on Cloud Run or a similar platform, replicate the env vars in the platform’s configuration and ensure the service account has appropriate network access to the Journey API.