# Quick Start Guide
Get your NS Trains MCP server up and running in 5 minutes!
## Prerequisites
- Python 3.11 or higher
- NS API key ([Get one here](https://apiportal.ns.nl/))
- Terminal/Command line
## Installation (5 steps)
### 1. Install `uv` (if not already installed)
```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Or use Homebrew on macOS
brew install uv
```
### 2. Clone and navigate to the project
```bash
cd mcp-server-ns-bridge
```
### 3. Install dependencies
```bash
# Add uv to PATH (if just installed)
export PATH="$HOME/.local/bin:$PATH"
# Install all dependencies
uv sync --all-extras
```
### 4. Set up your API key
```bash
# Copy the environment template
cp .env.example .env
# Edit the .env file and add your NS API key
# NS_API_KEY=your_actual_api_key_here
```
On macOS/Linux, you can use:
```bash
echo "NS_API_KEY=your_actual_api_key_here" > .env
```
### 5. Test the installation
```bash
uv run pytest
```
You should see: `11 passed`
## Usage
### Option A: Test with MCP Inspector (Recommended for first-time)
```bash
uv run mcp dev src/ns_bridge/server.py
```
This opens an interactive inspector where you can test the MCP tools.
### Option B: Install in Claude Desktop
```bash
uv run mcp install src/ns_bridge/server.py
```
This automatically configures Claude Desktop to use your server.
### Option C: Manual Claude Desktop Configuration
1. Open Claude Desktop config:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
2. Add this configuration (replace the path with your actual project path):
```json
{
"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"
}
}
}
}
```
3. Restart Claude Desktop
## Example Queries
Once configured with Claude Desktop, try these queries:
### Find Stations
```
Find train stations in Amsterdam
```
### Plan a Trip
```
I need to travel from Utrecht to Amsterdam tomorrow at 9 AM.
Show me the train options with prices.
```
### Check Departures
```
What trains are departing from Rotterdam Centraal in the next hour?
```
### Compare Routes
```
What's the fastest way to get from Den Haag to Groningen?
How much would a first-class ticket cost?
```
## Common Station Codes
Here are some frequently used station codes:
- `ut` - Utrecht Centraal
- `asd` - Amsterdam Centraal
- `rtd` - Rotterdam Centraal
- `gvc` - Den Haag Centraal
- `ehv` - Eindhoven Centraal
- `nm` - Nijmegen
- `gn` - Groningen
- `ams` - Amsterdam Sloterdijk
- `ledn` - Leiden Centraal
- `zl` - Zwolle
Use `search_stations` to find codes for other stations!
## Troubleshooting
### "Module not found" error
Make sure you're using `uv run` before commands:
```bash
uv run pytest # ✓ Correct
pytest # ✗ Wrong
```
### API key not working
1. Verify you registered at [NS API Portal](https://apiportal.ns.nl/)
2. Check you subscribed to the required APIs:
- Reisinformatie API
- NS-APP Stations API
3. Ensure your `.env` file exists and contains the key
4. Restart your terminal/Claude Desktop after adding the key
### Claude Desktop doesn't see the server
1. Check the path in `claude_desktop_config.json` is absolute
2. Verify `uv` is installed and accessible
3. Check Claude Desktop logs for errors
4. Restart Claude Desktop completely
### Permission denied
```bash
chmod +x src/ns_bridge/server.py
```
## Development Workflow
If you want to modify or extend the server:
```bash
# Format code
uv run black src/ tests/
# Lint code
uv run ruff check --fix src/ tests/
# Run tests
uv run pytest
# Run tests with coverage
uv run pytest --cov
# Type check
uv run mypy src/
```
See [DEVELOPER_TOOLS.md](DEVELOPER_TOOLS.md) for detailed information about development tools.
## Next Steps
1. Read the [README.md](README.md) for complete documentation
2. Check [DEVELOPER_TOOLS.md](DEVELOPER_TOOLS.md) to understand the development stack
3. Explore the NS API specs in `.ns-apis/` directory
4. Consider adding new features (disruptions, facilities, etc.)
## Getting Help
- Check the [README](README.md) for detailed documentation
- Review error messages - they usually include helpful hints
- NS API Documentation: https://apiportal.ns.nl/
- MCP Documentation: https://modelcontextprotocol.io/
## What's Next?
This is a basic implementation with:
- ✓ Station search
- ✓ Trip planning
- ✓ Pricing information
- ✓ Real-time departures
**Future ideas**:
- Add disruptions and maintenance notifications
- Include station facilities (parking, bike storage, etc.)
- Support for international routes
- Journey crowdedness predictions
- Historical delay statistics
Happy travels! 🚂
