Indian Railways MCP server

A remote Model Context Protocol server (streamable HTTP, stateless) that gives LLM clients such as Claude Code, Claude Desktop and claude.ai structured access to Indian Railways data. It covers stations, timetables, trains between stations, station boards, multi-train journeys and nearby stations. It also covers punctuality history (how late a train usually runs), and, when a source is configured, seat availability and fares.

The tools are small, composable building blocks rather than one fixed journey planner. The model combines them, for example "no direct train → find a well-served station near the destination → find connections to it".

Disclaimer. This is an independent, non-commercial project, not affiliated with Indian Railways, IRCTC, CRIS/NTES or any of the sites it can query. Data can be wrong or out of date: always confirm with official channels before travelling. Third-party sources are off by default. If you enable them, checking and following their terms of use is your responsibility. See DISCLAIMER.md.

Design documentation, with C4, UML sequence/class/deployment and flowchart diagrams, is in docs/README.md.

Principles

• No fabricated data. Every tool returns real source data or an error with a code (NOT_FOUND, UNSUPPORTED, UPSTREAM_UNAVAILABLE, RATE_LIMITED, INVALID_INPUT, UPSTREAM_AUTH). Nothing is estimated, padded or silently defaulted, and a failure is never turned into an empty "success".

• Provenance on every answer. The source object gives the provider, data_as_of, possibly_outdated and retrieved_at, plus notes when a fallback source answered.

• Timing kinds are explicit. Timetable tools return timing_kind: "scheduled". Punctuality figures are historical delays, given with their period and run count. Availability and fares carry observed_at, because some sources serve cached snapshots.

• Cross-source verification of static facts. Every query that returns timetable or station facts asks all independent sources in parallel and compares them field by field. That covers times to the exact minute, running days and classes as sets, and distances and coordinates within 1–2 km. Each item carries verification.status:

  • confirmed: at least two sources agree on every compared field

  • partially_confirmed: some fields come from one source only

  • majority: sources disagree, but at least two independent sources agree on the value shown. When that value replaced the official timetable's (e.g. a train retimed after the timetable was printed), the original is listed under corrections

  • conflict: sources disagree with no majority, and each source's value is listed

  • single_source

  • not_checked: the time budget ran out

  Values are shown even when unconfirmed, always with this flag. The archived 2016 dataset counts as evidence for stations only, never for timetables. Coordinates copied between datasets don't count twice. Data that changes all the time (seats, fares) is not cross-checked; it carries observed_at / last_updated instead. Cross-checking needs the unofficial sources enabled; without them everything is single_source. The time budget per call is VERIFY_BUDGET_MS (default 20 s). Upstream responses are cached (routes for 24 h), so repeated checks are fast.

• Pluggable providers. Tools call a registry that tries providers in priority order per capability (src/providers/registry.ts). To add a source, implement the interfaces in src/providers/types.ts and register it in src/config.ts. The MCP interface doesn't change.

Related MCP server: Indian Railway MCP

Tools

All tools are read-only and annotated readOnlyHint: true.

Data sources

Priority per capability, first answer wins:

• schedule: official → eRail → archived

• trains between: official → ConfirmTkt → eRail → archived

• availability and fares: ConfirmTkt (when enabled)

• delay history: etrain → NTES → RailRadar. The first that answers is the primary; the others cross-check it.

When an answer comes from a lower-priority source, source.notes says why.

About the unofficial sources. Indian Railways publishes no free public API for availability, fares or delay history. ConfirmTkt and eRail are undocumented endpoints of third-party sites. They may change without notice, and using them may breach those sites' terms. They ship disabled; enable them only if you've decided that's acceptable for your use. With them disabled, those tools return UNSUPPORTED with instructions.

Run locally with Docker (recommended)

git clone https://github.com/shubhamyadav8901/railways-mcp.git && cd railways-mcp
docker compose up -d --build        # http://localhost:3000/mcp
curl -s localhost:3000/healthz      # {"status":"ok",...}

The timetable datasets (data/*.json.gz) are included in the repository and the image; rebuilding them is optional (see "Building the datasets"). Optional settings go in .env, using .env.example as the template: unofficial sources and their client settings, geocoder and verification budget. Run docker compose up -d after changing them. The port is bound to 127.0.0.1 only.

Connect Claude Code:

claude mcp add --transport http indian-railways http://localhost:3000/mcp

Claude Desktop and claude.ai connect to remote URLs only (Settings → Connectors). For those, see "Optional: hosting" below.

Inspect or test:

npx @modelcontextprotocol/inspector --cli http://localhost:3000/mcp --transport http --method tools/list

Without Docker

npm ci
npm run build && npm start          # or: npm run dev

Building the datasets

npm run build:data                  # data/datameet2016.json.gz (downloads ~100 MB raw once)
# official timetable → data/tag2026.json.gz: see scripts/tag/README.md

Configuration

All settings are optional; see .env.example.

Optional: hosting

The same image runs on any Docker host; it listens on PORT. Set ALLOWED_HOSTS to the public hostname. Hosting is only needed to use the server from claude.ai or Claude Desktop. Free options:

• Hugging Face Spaces (Docker). 16 GB RAM. Set PORT=7860.

• Render free tier. 512 MB RAM, which is tight with both datasets loaded.

Both sleep when idle.

Operations

Check external sources. Unofficial endpoints can change without notice. The server fails safe: you get typed errors, never wrong data. To find out which source broke:

npm run smoke                 # one live call per source, exit code 1 if any fails
npm run smoke -- etrain ntes  # only these

Refresh the data when a new Trains at a Glance is published (yearly), or to pick up station changes:

pip install -r scripts/tag/requirements.txt
python3 scripts/tag/download.py                 # TAG PDFs → data/raw/tag2026/ (update the year in the script)
python3 scripts/tag/build_equivalences.py --erail-cache <dir> --ct-cache <dir>   # verified station-code equivalences
python3 scripts/tag/build.py                    # → data/tag2026.json.gz
python3 scripts/tag/validate.py --sample 150 --cache <dir>   # accuracy vs eRail; review before shipping
docker compose up -d --build

Seasonal timings. Konkan-route trains have monsoon timings (TAG: 10 Jun–31 Oct). Tools choose the timings valid on the travel date, or on today when no date is given, and say so in the response.

Development

npm test          # vitest: core logic, providers (synthetic fixtures), MCP protocol in-memory + over HTTP
npm run typecheck

Layout:

• src/core/: domain types, time arithmetic, connection search

• src/providers/: provider contracts, registry, local timetables, adapters

• src/tools/: MCP tool definitions

• src/server.ts: HTTP transport

Contributing

Contributions are welcome: bug reports, data corrections, new data sources, parser improvements and docs. Read CONTRIBUTING.md for the ground rules (never fabricate data, provenance on every answer, unofficial sources opt-in, synthetic fixtures only) and the development setup. Please follow the Code of Conduct, and report security issues privately as described in SECURITY.md.

Licence

Code: Apache License 2.0. See NOTICE for attributions and DISCLAIMER.md for the bundled data and third-party sources.