# mcp-sncf-navitia

MCP server for French railway queries via the [Navitia API](https://www.navitia.io) (SNCF coverage).
Search for French stations, plan journeys, and get departure boards — powered by SNCF data.

**Status:** Ready

---

## Prerequisites

- [Bun](https://bun.sh) runtime (`curl -fsSL https://bun.sh/install | bash`)
- A [Navitia](https://www.navitia.io) API key (free registration)

---

## Install

```bash
git clone git@github.com:McCullonas/mcp-sncf-navitia.git
cd mcp-sncf-navitia
bun install
```

---

## Configuration

| Variable | Required | Description |
|----------|----------|-------------|
| `NAVITIA_API_KEY` | Yes | Your Navitia API token |

Register for free at [navitia.io](https://www.navitia.io). The free tier provides access to
SNCF data across France.

---

## Available Tools

### `sncf_search_places`
Search for French railway stations and places by name.

**Parameters:**
- `query` — Station or place name (e.g. `"Paris Gare du Nord"`, `"Lyon Part-Dieu"`)
- `count` *(optional)* — Max results (default 5)

Returns: place name, ID, type, and coordinates.

### `sncf_get_journeys`
Get train journey options between two locations.

**Parameters:**
- `from` — Origin place ID (from `sncf_search_places`)
- `to` — Destination place ID
- `datetime` *(optional)* — ISO 8601 departure datetime (default: now)
- `count` *(optional)* — Number of journey options (default 3)

Returns: routes, legs, transfers, duration, walking segments, departure/arrival times.

### `sncf_get_departures`
Get upcoming departures from a station.

**Parameters:**
- `stopId` — Stop area ID (from `sncf_search_places`)
- `datetime` *(optional)* — ISO 8601 datetime (default: now)
- `count` *(optional)* — Number of departures (default 10)

Returns: line info, direction, departure time, network info.

---

## MCP Client Configuration

Add to your `settings.json`:

```json
{
  "mcpServers": {
    "sncf-navitia": {
      "command": "bun",
      "args": ["run", "/path/to/mcp-sncf-navitia/src/index.ts"],
      "env": {
        "NAVITIA_API_KEY": "your-key-here"
      }
    }
  }
}
```

---

## Development

```bash
NAVITIA_API_KEY=your-key bun run src/index.ts
bun build src/index.ts --outdir dist --target node
```

---

## Data Source

Queries the [Navitia API](https://www.navitia.io) with SNCF coverage, which includes
intercity, regional (TER), and high-speed (TGV/Inoui) services across France. Navitia is
operated by Kisio Digital, an SNCF subsidiary.

---

## Licence

MIT