Navitia MCP Server

An MCP server exposing the Navitia public-transport API: journey planning, place search, realtime departures and timetables, usable from Claude Desktop, Claude Code, or any MCP client.

→ Full usage guide — install, client setup, worked examples, tool reference, response shapes and troubleshooting.

Tools

Tool	What it does
`search_places`	Geocode / autocomplete stations, addresses, POIs, cities — returns the object ids the other tools need
`search_pt_objects`	Find networks, lines, routes and stops by name (e.g. "metro 14" → a `line:` id) for use as a `line_id` filter
`places_nearby`	Stops and POIs within a radius of a coordinate
`plan_journey`	Door-to-door multi-modal itineraries (with disruptions), with optional per-line preferences
`next_departures` / `next_arrivals`	Realtime departure/arrival boards for a stop
`stop_schedules`	Timetable at a stop, grouped by line and direction
`terminus_schedules`	Station-display board for one line at a stop, grouped by destination (needs a `line_id` from `search_pt_objects`)
`route_schedules`	Full timetable grid for a line or route

The server is scoped to a single coverage region (default Île-de-France, fr-idf) set via the NAVITIA_REGION env var — tools take no region parameter. Set NAVITIA_REGION=fr-se for the southeast (Lyon), sncf for national rail, etc.

Configuration

Env var	Required	Default	Purpose
`NAVITIA_API_KEY`	yes	—	Your Navitia token
`NAVITIA_REGION`	no	`fr-idf`	Coverage region id the server is scoped to
`NAVITIA_BASE_URL`	no	`https://api.navitia.io/v1`	API root (override for a self-hosted Navitia)

Setup

You need a Navitia API token (request one via navitia.io / Hove). The server reads it from NAVITIA_API_KEY only — never commit it. For local runs, copy .env.example to .env (gitignored) or export the variable in your shell.

npm install
npm run build

Claude Code

claude mcp add navitia --env NAVITIA_API_KEY=your-token --env NAVITIA_REGION=fr-idf -- node /absolute/path/to/dist/index.js

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "navitia": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "NAVITIA_API_KEY": "your-token",
        "NAVITIA_REGION": "fr-idf"
      }
    }
  }
}

Line preferences (experimental)

plan_journey can express a taste for or against a line instead of a hard rule:

Parameter	Effect	Typical phrasing
`prefer_lines: ["line:…"]`	Favours the line — itineraries using it rank higher	"I'd rather take metro 14"
`avoid_lines: ["line:…"]`	Proposes the line less, without removing it	"I'd like to avoid metro 14, but not rule it out"
`forbidden_uris: ["line:…"]`	Excludes the line outright	"never put me on metro 14"

All three take ids from search_pt_objects; prefer_lines / avoid_lines reject anything that is not a line: id rather than sending it on.

Preferences map to Navitia's experimental flag, one per line:

_features_flags[]=boost_line({line_id},{boost_factor})

with boost_factor = 3 for a preferred line and 0.4 for an avoided one.

Because boosting changes what the default ordering means, a response that used line preferences is re-ordered by the reliability rank in each journey's criteria_ranker — rank 1 first — and carries ordered_by: "reliability" so the client can explain the order it is showing. Without preferences, the API's own order is left untouched and ordered_by is absent.

The flag is experimental and depends on server-side support: an instance that does not implement it may ignore it or return an error, which the tool relays unchanged.

Usage notes

Datetimes are ISO 8601 in the region's local time (e.g. 2026-06-11T17:30); responses use the same format.
Ids: find stops/addresses with search_places (stop_area:…), and lines/networks with search_pt_objects (line:…), then feed them to the journey/departure/schedule tools.
terminus_schedules requires a line_id — resolve it with search_pt_objects first (e.g. "metro 14").
plan_journey calls always carry the technical parameter _frontend=gormun, which identifies this caller to Navitia. It is a constant, not a tool input.
Line preferences (prefer_lines / avoid_lines on plan_journey) nudge the ranking; forbidden_uris removes a line entirely. See Line preferences.
All tools are scoped to the NAVITIA_REGION coverage; no per-call region parameter. To serve several regions, run one instance per region.
Responses are deliberately slimmed (no geojson/links) to stay LLM-friendly; large results are truncated at 50 kB.

Output format

Tools return slimmed JSON — Navitia's HATEOAS links, geojson geometries and deep fare/co2 trees are dropped so the payload stays inside a model's context. Presentation is the client's job, not the server's.

Time-sensitive responses (plan_journey, next_departures, next_arrivals, stop_schedules, terminus_schedules, route_schedules) carry a top-level now — the API's own context.current_datetime, in the region's local timezone. Compute countdowns ("dans 3 min") against that field, never against the reader's clock, which may sit in another timezone.

Each journey also carries Navitia's criteria_ranker when the API supplies it — that journey's 1-based rank for asap, less_transfers, less_walking and reliability, 1 being the best on that criterion. It is what the line-preference re-ordering sorts on, and a client can reuse it to tag itineraries.

prompts/agent-system-prompt.md is a ready-to-use strict system prompt for an agent driving this server: it specifies the board layouts (departure boards, journey chains, timetables), the anti-fabrication rules, and the id-resolution protocol.

Development

NAVITIA_API_KEY=your-token npm run dev          # run from source
npx @modelcontextprotocol/inspector node dist/index.js   # interactive testing

See docs/USAGE.md for the full guide, and docs/USAGE.md#12-troubleshooting when something returns nothing.