NS Bridge

You have an MCP server that lets your AI assistants interact with the Netherlands NS API for route planning, pricing, and live departure information. It supports multiple MCP clients and provides practical tools to find stations, plan trips, and view real-time departures, enabling you to build conversational travel assistants and automation around NS data.

How to use

Invoke the MCP server from any MCP-compatible client to access station search, trip planning, and live departure data. Use natural language prompts to find stations by name or country, plan routes with pricing and class options, and fetch real-time departures for a chosen station. You can run the server locally in development mode for interactive testing, then connect your client or assistant to start asking questions like “What trains depart from Utrecht Centraal in the next hour?” or “Show me the fastest route from Amsterdam to Groningen.” Text prompts are translated into MCP requests that the server forwards to the NS APIs and returns structured results.

How to install

Prerequisites you need before installation include an NS API key and a supported runtime environment. Choose one installation method that fits your workflow.

# Option 1: Docker (easiest) 
docker pull ezegodoy26/mcp-server-ns-bridge:latest

# Option 2: uv (recommended for development)
# After cloning, run development server
uv run mcp dev src/ns_bridge/server.py

# Option 3: pip (traditional Python workflow)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"

Additional usage notes

Configure your MCP client to point at the server as shown in the examples. For development, you can run the server with the uv-based command to enable interactive testing. For production or broader client support, you can run the server in a Docker container or use the uv-based path with your own directory containing the server code.

Configuration and examples

The server can be run via Docker or uv with environment variables to provide your NS API key. Use the following example configurations as a starting point in your MCP client setup.

{
  "mcpServers": {
    "ns-bridge": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e",
        "NS_API_KEY",
        "ezegodoy26/mcp-server-ns-bridge:latest"
      ],
      "env": {
        "NS_API_KEY": "your_api_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "ns-bridge": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-server-ns-bridge",
        "run",
        "src/ns_bridge/server.py"
      ],
      "env": {
        "NS_API_KEY": "your_api_key_here"
      }
    }
  }
}

Security and keys

Keep your NS API key secure. Do not commit keys to code repositories or share them publicly. Use environment variables to supply keys to the MCP server, and ensure your client configuration only exposes allowed endpoints and actions.

Troubleshooting

If you encounter connection issues, verify that the server is running, the MCP client is configured to use the correct stdio or HTTP method, and the NS API key is accessible to the server process. Check that the NS APIs you subscribed to are active and that your key has the necessary permissions for station, trip, and departure data.

Notes

This MCP server is compatible with any MCP client. You can query station codes, plan routes with multiple options, and fetch current departures with live updates.

Tool capabilities

You can use the following MCP tools to interact with NS data: search_stations to find stations by name or country, search_trips to plan routes with pricing and travel class options, and get_departures to view real-time departure boards and monitor delays or platform changes.

Available tools

search_stations

Find train stations by name or country code, filtering results to return relevant station codes for trip planning.

search_trips

Plan routes between stations, retrieve multiple options with connections, view leg-by-leg details, pricing, and travel class options.

get_departures

Fetch real-time departure boards for a station, including delays, cancellations, and platform changes.