Skip to main content
Glama

MCP Server for Netherlands NS Trains

mcp-name: ns-bridge

Python 3.11+ License: MIT Ruff Checked with mypy Pre-commit Tests: pytest Docker

A Model Context Protocol (MCP) server that enables AI assistants to interact with the Netherlands Railways (NS) API for route planning, pricing, and real-time departure information.

Compatible with any MCP client, including Claude Desktop, custom implementations, and AI agent frameworks.

Features

MCP Tools

  1. search_stations - Find train stations by name or country

    • Search by station name

    • Filter by country code

    • Returns station codes needed for trip planning

  2. search_trips - Plan routes between stations

    • Get multiple trip options with connections

    • View detailed leg-by-leg journey information

    • See pricing with discount options

    • Choose travel class (1st or 2nd)

    • Search by departure or arrival time

  3. get_departures - View real-time departure boards

    • See upcoming departures from any station

    • Track delays and cancellations

    • Monitor platform changes

MCP Resources

  • station://{code} - Get detailed information about a specific station

Related MCP server: MCP Trenitalia

Installation

Prerequisites

  • NS API key from NS API Portal

  • Choose one installation method:

    • Docker (easiest - no Python installation needed)

    • uv (recommended for development)

    • pip (traditional Python workflow)

Option 1: Docker (Easiest)

Prerequisites: Docker Desktop or Docker Engine

# Pull the pre-built image from Docker Hub
docker pull ezegodoy26/mcp-server-ns-bridge:latest

Then configure your MCP client (see Usage section below for configuration examples).

For detailed Docker usage, troubleshooting, and advanced options, see DOCKER.md.

# Clone the repository
cd mcp-server-ns-bridge

# Install dependencies
uv sync --all-extras

# Set up pre-commit hooks (recommended for development)
uv run pre-commit install

# Copy environment template
cp .env.example .env

# Edit .env and add your NS API key
# NS_API_KEY=your_actual_api_key_here

Option 3: Setup with pip

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

# Set up environment
cp .env.example .env
# Edit .env and add your NS API key

Getting an NS API Key

  1. Go to NS API Portal

  2. Create an account

  3. Subscribe to the following APIs:

    • Reisinformatie API (Travel Information)

    • NS-APP Stations API

  4. Copy your subscription key

  5. Add it to your .env file as NS_API_KEY

Usage

Running the MCP Server

Development Mode (with Inspector)

export PATH="$HOME/.local/bin:$PATH"
uv run mcp dev src/ns_bridge/server.py

This opens the MCP Inspector for interactive testing.

Configuring MCP Clients

This server works with any MCP-compatible client. Below are configuration examples for popular clients.

Claude Desktop

Automatic Installation:

uv run mcp install src/ns_bridge/server.py

This will automatically configure Claude Desktop to use your MCP server.

Manual Configuration:

Add to your Claude Desktop config file (location varies by OS):

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

For Docker installation:

{
  "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"
      }
    }
  }
}

Note: The -e NS_API_KEY in the args array tells Docker to pass the environment variable from the host (set by the env section) into the container. Without this, the API key won't be available inside Docker.

For uv installation:

{
  "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"
      }
    }
  }
}

After updating the configuration, restart your MCP client to load the server.

Other MCP Clients

For other MCP-compatible clients (custom implementations, AI agent frameworks, etc.), refer to your client's documentation for stdio server configuration. The server accepts standard MCP protocol messages via stdin/stdout.

Example Queries

Once configured, you can ask your AI assistant:

  • "What trains are departing from Utrecht Centraal in the next hour?"

  • "Find me a train from Amsterdam to Rotterdam tomorrow at 9 AM"

  • "What's the fastest route from Den Haag to Groningen?"

  • "How much does a first-class ticket from Eindhoven to Maastricht cost?"

  • "Show me stations near the German border"

Development

Project Structure

mcp-server-ns-bridge/
├── src/
│   └── ns_bridge/
│       ├── __init__.py          # Package initialization
│       ├── server.py            # MCP server implementation
│       ├── ns_api_client.py     # NS API wrapper
│       ├── models.py            # Data models (Pydantic)
│       └── config.py            # Configuration management
├── tests/                       # Test suite
├── pyproject.toml               # Project configuration & dependencies
├── .env.example                 # Environment template
└── README.md                    # This file

Developer Tools

This project uses modern Python development tools for code quality:

Pre-commit Hooks

Pre-commit hooks automatically check your code before each commit:

  • General checks: Trailing whitespace, EOF fixes, YAML/TOML validation

  • Ruff: Fast linting and code formatting

  • MyPy: Static type checking

  • Bandit: Security vulnerability scanning

# Install pre-commit hooks (one-time setup)
uv run pre-commit install

# Run manually on all files
uv run pre-commit run --all-files

# Hooks will automatically run on git commit

Code Formatting & Linting

You can also run tools manually:

# Format code with Ruff
uv run ruff format src/ tests/

# Lint and auto-fix
uv run ruff check --fix src/ tests/

# Type checking
uv run mypy src/

# Security scanning
uv run bandit -r src/

See DEVELOPER_TOOLS.md for detailed documentation on each tool and why we use them.

Testing

  • pytest: Test framework

  • pytest-asyncio: Async test support

  • pytest-cov: Code coverage

  • pytest-httpx: HTTP mocking for API tests

Run tests:

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov

# Run specific test file
uv run pytest tests/test_models.py

# Run with verbose output
uv run pytest -v

Virtual Environment Note

Yes, uv is compatible with virtual environments! uv automatically creates and manages a .venv directory in your project. You can activate it manually if needed:

source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

However, uv run automatically uses the virtual environment, so activation is optional for most tasks.

API Documentation

NS API Endpoints Used

  1. Stations API (/nsapp-stations/v2)

    • Search and list train stations

    • Filter by country

  2. Trips API (/reisinformatie-api/api/v3/trips)

    • Route planning with connections

    • Pricing information

    • Support for via stations

  3. Departures API (/reisinformatie-api/api/v2/departures)

    • Real-time departure information

    • Delay and cancellation tracking

Station Codes

Common station codes:

  • ut - Utrecht Centraal

  • asd - Amsterdam Centraal

  • rtd - Rotterdam Centraal

  • gvc - Den Haag Centraal

  • ehv - Eindhoven Centraal

  • nm - Nijmegen

  • gn - Groningen

Use the search_stations tool to find more station codes.

Contributing

Suggestions and improvements are welcome!

Development Workflow

  1. Create a feature branch

  2. Make your changes

  3. Run the test suite: uv run pytest

  4. Pre-commit hooks will automatically run on commit (or run manually: uv run pre-commit run)

  5. Submit a pull request

Note: Pre-commit hooks automatically handle formatting, linting, type checking, and security scanning.

License

MIT License - see LICENSE file for details

Acknowledgments

Roadmap

Future enhancements planned:

  • Add support for disruptions API

  • Include station facilities information

  • Add journey details (crowdedness predictions)

  • Support for international routes

  • Caching for frequently accessed data

  • Rate limiting to respect API quotas

Available Tools

3 tools
get_departuresA

Get upcoming train departures for a specific station.

Use this to check the departure board at a station, including real-time updates about delays, cancellations, and platform changes.

Args: station: Station code (e.g., "ut" for Utrecht Centraal). Use search_stations to find codes. max_journeys: Maximum number of departures to return (default: 10, max: 40) date_time: Date and time to show departures from in ISO format. Defaults to current time.

Returns: A dictionary containing: - station: Station code - departures: List of departures with: - direction: Destination of the train - name: Train identification (e.g., "Intercity 2800") - planned_time: Scheduled departure time - actual_time: Actual departure time (if different) - planned_track: Scheduled platform - actual_track: Actual platform (if changed) - cancelled: Whether the departure is cancelled - delay_minutes: Delay in minutes (if applicable) - count: Number of departures returned

Example: get_departures(station="ut", max_journeys=5) get_departures(station="asd", date_time="2025-11-20T08:00:00")

Inputs: station (required), max_journeys, date_time. Returns: object

search_stationsA

Search for train stations by name or filter by country.

Use this tool to find station codes needed for trip planning.

Args: query: Search query for station name (minimum 2 characters). Leave empty to list all stations. country_codes: Comma-separated country codes to filter (e.g., "nl,de,be"). Common codes: nl (Netherlands), de (Germany), be (Belgium) limit: Maximum number of results to return (default: 10, max: 100)

Returns: A dictionary containing: - stations: List of matching stations with their codes and locations - count: Number of stations returned

Example: search_stations(query="Amsterdam", limit=5) search_stations(country_codes="nl", limit=20)

Inputs: query, country_codes, limit. Returns: object

search_tripsA

Search for train trips between two stations with pricing information.

This is the main tool for route planning. It returns trip options with detailed information about connections, travel times, and prices.

Args: origin: Origin station code (e.g., "ut" for Utrecht, "asd" for Amsterdam). Use search_stations to find codes. destination: Destination station code (e.g., "rtd" for Rotterdam). Use search_stations to find codes. date_time: Departure/arrival date and time in ISO format (e.g., "2025-11-18T14:30:00"). Defaults to current time. search_for_arrival: If true, date_time is treated as arrival time. If false (default), it's departure time. via_station: Optional intermediate station code to route through travel_class: Travel class - either "first" or "second" (default: "second") discount: Discount type - "none" (default), "20_percent", or "40_percent" num_trips: Number of trip options to return (default: 5)

Returns: A dictionary containing: - trips: List of trip options, each with: - duration_minutes: Total travel time - transfers: Number of transfers required - departure_time: Planned departure time - arrival_time: Planned arrival time - status: Trip status (e.g., "NORMAL", "CANCELLED") - legs: List of individual journey segments - price: Fare information in cents and formatted - origin: Origin station name - destination: Destination station name

Example: search_trips(origin="ut", destination="asd", num_trips=3) search_trips(origin="rtd", destination="ams", date_time="2025-11-20T09:00:00", travel_class="first")

Inputs: origin (required), destination (required), date_time, search_for_arrival, +4 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: get_departures retrieves departure board information for a single station, search_stations finds station codes, and search_trips plans routes between stations. The descriptions clearly differentiate their functions, making misselection unlikely.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with snake_case naming: get_departures, search_stations, and search_trips. The verbs 'get' and 'search' are appropriately chosen for their respective operations, creating a predictable and readable naming convention throughout.

    Tool Count3/5

    With only 3 tools, the server feels somewhat thin for a train travel domain. While the tools cover core functionalities (departure info, station search, trip planning), additional operations like booking tickets, checking disruptions, or managing favorites would enhance coverage. The count is borderline minimal but functional.

    Completeness4/5

    The tool surface covers essential train travel workflows: finding stations, checking departures, and planning trips with pricing. Minor gaps exist, such as no ticket booking, real-time disruption alerts, or saved trip management, but agents can work effectively with the provided tools for basic planning and information retrieval.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      An MCP server for Swiss Federal Railways (SBB) open data, enabling AI models to query real-time disruptions, passenger frequencies, station details, and more without an API key.
      9
      26 PyPI
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server for real-time Italian railway data, enabling natural language queries about train schedules, delays, departures, arrivals, and live tracking via the Viaggiatreno API.
      7
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that exposes the Deutsche Bahn public transport API to any MCP-compatible client (Claude Desktop, Cursor, Cline, Continue, etc.). Five tools cover station search, departures, journey planning, trip details, and nearby stations.
      6
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server for querying Dutch railway data via the NS API, with planned tools for station search, departures, trip planning, and disruptions.
      -