Metadata-Version: 2.4
Name: irail-mcp
Version: 0.1.1
Summary: MCP server for Belgian railway data via the iRail API
Project-URL: Homepage, https://github.com/HansF/irail-mcp
Project-URL: Repository, https://github.com/HansF/irail-mcp
Project-URL: Issues, https://github.com/HansF/irail-mcp/issues
Author: Hans F
License: MIT
License-File: LICENSE
Keywords: belgium,irail,mcp,nmbs,railway,sncb,trains
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: httpx>=0.25.0
Requires-Dist: mcp>=1.1.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# iRail MCP Server

> **Disclaimer:** This project was vibe coded and is **not affiliated with or supported by [iRail vzw](https://hello.irail.be)**. Train data may be inaccurate or outdated. Always verify with official sources ([belgiantrain.be](https://www.belgiantrain.be) or the NMBS/SNCB app) before making travel decisions.

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that provides Belgian railway travel information via the [iRail API](https://api.irail.be).

## Features

- **Search Stations** - Find Belgian railway stations by name
- **Live Departures/Arrivals** - Real-time departure and arrival boards
- **Find Connections** - Route planning between stations with transfers
- **Train Information** - Detailed stops, delays, and platforms for a specific train
- **Network Disturbances** - Current disruptions and planned maintenance

## Installation

Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).

```bash
git clone https://github.com/HansF/irail-mcp.git
cd irail-mcp
uv venv && source .venv/bin/activate
uv pip install -e .
```

## Usage with Claude Code

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "irail": {
      "command": "uvx",
      "args": ["irail-mcp"]
    }
  }
}
```

Then ask Claude things like:
- "What trains leave Brussels Central in the next hour?"
- "Find a route from Antwerp to Bruges at 2:30 PM tomorrow"
- "Are there any disruptions on the Belgian rail network?"
- "Show me details for train IC2240"

## Tools

### search_stations
Search for stations by name.
- `query` (required) - Station name or partial name
- `lang` (optional) - Language: en, nl, fr, de, it

### get_liveboard
Real-time departures or arrivals from a station.
- `station` (required) - Station name
- `date` (optional) - YYYY-MM-DD, "today", "tomorrow", "+2 days"
- `time` (optional) - HH:MM (24h)
- `arrival` (optional) - Show arrivals instead of departures
- `lang` (optional)

### find_connections
Find routes between two stations.
- `from_station` (required) - Departure station
- `to_station` (required) - Destination station
- `date`, `time`, `lang` (optional)
- `arrival_time` (optional) - If true, time is desired arrival time

### get_train_info
Detailed information about a specific train.
- `train_id` (required) - e.g. "IC1234" or "BE.NMBS.IC1234"
- `date`, `lang` (optional)

### get_disturbances
Current network disruptions and planned works.
- `lang` (optional)

## Running Tests

```bash
uv pip install -e ".[dev]"
python -m pytest tests/ -v
```

## API Compliance

- Rate limited to 3 requests/second per iRail guidelines
- Proper User-Agent header set
- 30-second timeout for slow responses

## License

MIT

## References

- [iRail API](https://api.irail.be) - [Documentation](https://docs.irail.be)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [NMBS/SNCB](https://www.belgiantrain.be)
