Official NS Real-Time Travel MCP Server

Overview

The Official NS Real-Time Travel MCP Server acts as a lightweight proxy and context provider for Dutch Railways (NS) real-time train data and disruption information. It queries the official NS API on your behalf, normalizes responses, and exposes them via an MCP-compatible interface so language models or integrations can request up-to-date travel context reliably.

This server is useful when you need a dependable, developer-friendly way to supply model-driven agents, chatbots, or monitoring tools with the latest departures, delays, and disruption notices without embedding NS credentials in multiple places. It centralizes API access, adds optional caching and basic rate-management, and formats responses for easy consumption by downstream tools.

Features

• Fetches real-time departures, delays, and service disruptions from the official NS API
• MCP-compatible endpoints designed for use by LLM agents and context protocols
• Centralized API key management (keeps your NS credentials in one place)
• Configurable caching to reduce request volume and improve response times
• Docker-friendly and simple environment-based configuration
• Structured JSON responses normalized for easier parsing by clients
• Logging and configurable verbosity for debugging

Installation / Configuration

Quick start using Docker:

1. Run with Docker (replace YOUR_NS_API_KEY and optional PORT):

docker run -e NS_API_KEY=YOUR_NS_API_KEY -e PORT=8080 -p 8080:8080 ghcr.io/r-huijts/ns-mcp-server:latest

2. Or use docker-compose:

version: '3.8'
services:
  ns-mcp:
    image: ghcr.io/r-huijts/ns-mcp-server:latest
    environment:
      - NS_API_KEY=${NS_API_KEY}
      - PORT=8080
      - CACHE_TTL=30
    ports:
      - "8080:8080"

Environment variables (typical):

Configuration can also be supplied via a config file or container secret depending on deployment practices (e.g., Kubernetes Secrets).

Available Resources

• Source code and releases: https://github.com/r-huijts/ns-mcp-server
• Official NS developer API documentation: consult NS for current endpoints and quota/security policies
• Recommended deployment: run behind a reverse proxy (TLS termination) and use secret management for NS_API_KEY
• Optional: enable application-level caching or an external cache (Redis) if high throughput is required

API Usage Examples

The MCP server exposes REST endpoints tailored for context retrieval. Example requests below assume the server is running on localhost:8080.

Get departures for a station (by station code):

curl "http://localhost:8080/v1/departures?station=AMS" \
  -H "Accept: application/json"

Sample normalized response structure:

{
  "station": "AMS",
  "fetched_at": "2026-04-10T12:34:56Z",
  "departures": [
    {
      "train_id": "IC1234",
      "destination": "Rotterdam Centraal",
      "planned_time": "2026-04-10T12:45:00Z",
      "expected_time": "2026-04-10T12:50:00Z",
      "platform": "5",
      "status": "delayed"
    }
  ]
}

Fetch current disruptions:

curl "http://localhost:8080/v1/disruptions" \
  -H "Accept: application/json"

MCP tool metadata (if exposing as an LLM tool):

curl "http://localhost:8080/.well-known/mcp" \
  -H "Accept: application/json"

Use Cases

• LLM-driven travel assistant: Provide a chat model with fresh departure and disruption context during a user conversation so responses reference current delays and platform changes.
• Station display backend: Use the normalized departures endpoint to populate web or kiosk displays with consistent JSON data.
• Incident monitoring: Periodically poll /v1/disruptions to feed alerts into incident management systems or Slack notifications.
• Aggregation service: Combine NS real-time data with other transport modes (bus, tram) by centralizing NS access through the MCP server before merging with other providers.

Operational Notes

• Authentication: The server requires an NS API key. Keep this key in a secure secret store; do not embed it in client-side code.
• Rate limits: Respect NS API quotas. Use the server-side cache to reduce request load and protect against accidental spikes.
• Security: Run the MCP server behind HTTPS and apply standard hardening for containers. Limit access to the server to only trusted consumers when possible.
• Extensibility: The repo is structured to add additional endpoints or output formats — useful if you need GTFS-like exports or bespoke filtering.

For code, issues, and contributions, see the GitHub repository: https://github.com/r-huijts/ns-mcp-server.