japan-rail-mcp
A read-only MCP server for Japanese (Shinkansen-first) rail data: credential-free station lookup, plus live timetables, fares, seat classes, and stops when an Ekispert Standard Plan key is configured.
get_provider_status – Check which read-only capabilities are configured/disabled before querying.
search_stations – Resolve Japanese, English, or romanized names to canonical
jp:station:*IDs; returns ambiguous candidates (e.g. Osaka, Fukuoka) rather than guessing.search_trains – Find direct Shinkansen services between two resolved station IDs for an explicit
YYYY-MM-DD, with optional time/service/operator filters and pagination (max 20 per request).get_train_details – Read a train and its ordered stops by opaque
trainId.get_availability – Check provider seat-inventory support; currently returns an explicit
unsupportedstatus with no invented counts.compare_trains – Sort direct-train candidates by departure, arrival, duration, or total fare without subjective recommendation.
search_journeys – Reserved for transfer itineraries; returns a structured unsupported error in v0.1.
get_station_details – Read bundled station metadata (names, operators, prefecture, Shinkansen lines, provenance) offline by ID.
evaluate_train_options – Re-rank recently searched trains against personal timing/budget/seat-class constraints with zero further provider requests (15-minute in-memory snapshot, max 200 records).
plan_shinkansen_trip – One provider search plus personal comparison in a single call.
get_personal_preferences – Inspect saved planning defaults and station-specific allowances without network access.
All tools are read-only, non-destructive, idempotent, and return JSON text plus schema-validated structuredContent with source provenance. No booking, login, payment, scraping, or transfer search; fares are not seat inventory and all successful tools require no writes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@japan-rail-mcp Search for stations matching 'Tokyo' and list their IDs."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
japan-rail-mcp
japan-rail-mcp is a read-only Model Context Protocol server for structured Japanese railway
data. Version 0.1 is deliberately Shinkansen-first: it provides a useful credential-free
station catalog and can query live Shinkansen timetables, fares, seat classes, and stops through a
deployment owner's Ekispert API Standard Plan key.
The server never books tickets, signs in to railway accounts, bypasses access controls, scrapes operator websites, or presents test fixtures as live data.
japan-rail-mcp is designed to share a common conceptual interface with china-rail-mcp, with the long-term goal of establishing interoperable schemas for railway MCP servers across countries.
This is an experimental interoperability convention, not an official railway or MCP standard.
Features
Capability | Without an API key | With |
Japanese, English, and romanized station search | Yes, bundled 58-station Shinkansen-focused catalog | Yes |
Ambiguous station candidates | Yes | Yes |
Direct Shinkansen timetable search | Explicitly unsupported | Yes, subject to the key's plan |
Fare amounts in numeric JPY | Explicitly unsupported | Yes |
Seat-class normalization | Explicitly unsupported | Yes |
Ordered train stops | Explicitly unsupported | Yes |
Reservation inventory / seat availability | Explicitly unsupported | Explicitly unsupported |
Transfer journey search | Explicitly unsupported in v0.1 | Explicitly unsupported in v0.1 |
All successful data includes source provenance. Railway timestamps are explicit ISO 8601 values
with the Japan offset, for example 2026-08-26T12:03:00+09:00. Relative dates such as “tomorrow”
must be resolved by the MCP client; the server requires YYYY-MM-DD.
Related MCP server: uk-rail-mcp
MCP tools
Tool | When to use it |
| Check configured providers and capability boundaries before a live query. |
| Resolve a name to one or more canonical |
| Search direct Shinkansen services between two resolved station IDs. |
| Read the ordered stops for an opaque |
| Check provider support; currently returns |
| Sort the same structured direct-train candidates without a subjective recommendation. |
| Reserved for transfer routes; returns a structured unsupported error in v0.1. |
| Read exact bundled station metadata by ID without a network request. |
| Re-evaluate recently searched trains against personal timing, budget, and seat-class constraints without another provider request. |
| Search once and compare candidates using saved or explicitly supplied personal constraints. |
| Read saved planning defaults and station-specific allowances without network access. |
Every tool is annotated read-only, non-destructive, and idempotent. Every successful tool result
includes both human-readable JSON text and MCP structuredContent validated against an output
schema.
Installation
Requirements: Node.js 22 or newer. CI uses Node.js 24 LTS.
git clone https://github.com/TakeruF/japan-rail-mcp.git
cd japan-rail-mcp
npm install
npm run buildStart the stdio server:
npm startAfter an npm release, clients can alternatively launch it with:
npx -y japan-rail-mcpLive Shinkansen data
Live timetable functionality requires an access key whose Ekispert API agreement includes the Standard Plan route-search endpoint. The free plan does not provide that core endpoint.
export EKISPERT_API_KEY='your-own-key'
npm startThe key is sent only to the configured Ekispert API endpoint. It is never returned in tool results or included in provider errors. The project does not include a shared key, sublicense provider data, or override the request limits attached to your agreement.
Client configuration
Claude Desktop
For a local checkout, add an entry like this and replace the absolute path:
{
"mcpServers": {
"japan-rail": {
"command": "node",
"args": ["/absolute/path/to/japan-rail-mcp/dist/index.js"],
"env": {
"EKISPERT_API_KEY": "your-own-key"
}
}
}
}Omit the env object for station search only. Prefer your client's secret-management facility
over committing keys to a configuration repository.
Codex
Register the built stdio command with Codex's MCP configuration, or use the CLI form supported by your installed Codex version:
codex mcp add japan-rail -- node /absolute/path/to/japan-rail-mcp/dist/index.jsProvide EKISPERT_API_KEY through the process environment or Codex's secret configuration when
live train data is required.
Tool examples
First resolve station candidates:
{
"query": "Osaka"
}The result deliberately includes both Osaka and Shin-Osaka when relevant. Then use the exact IDs:
{
"fromStationId": "jp:station:tokyo",
"toStationId": "jp:station:shin-osaka",
"date": "2026-08-26",
"departureAfter": "12:00",
"serviceTypes": ["shinkansen"],
"limit": 10,
"offset": 0
}A normalized fare is numeric and currency-safe:
{
"amount": 14720,
"currency": "JPY",
"formatted": "¥14,720",
"kind": "total"
}formatted is display-only; clients should use amount and currency for comparison.
One-call personal trip planning
Resolve canonical station IDs with search_stations, then call plan_shinkansen_trip:
{
"fromStationId": "jp:station:tokyo",
"toStationId": "jp:station:shin-osaka",
"stationReadyAt": "2026-10-13T11:40:00+09:00",
"arriveBy": "2026-10-13T16:00:00+09:00",
"maxFareJPY": 15000
}This makes one provider search and returns the personal comparison in the same tool call.
The departure-based query starts at stationReadyAt plus the effective boarding allowance;
its date and time are derived in Asia/Tokyo, including when the allowance crosses midnight.
It still requires an Ekispert Standard Plan key. Results identify dataMode: "provider_search".
An arrival deadline filters these departure-based candidates; it is not a backward timetable
search. At most 20 provider candidates are considered. Returned train IDs, including excluded
candidates, can be passed to evaluate_train_options to change preferences without another
provider request. Changing the route or requesting trains outside that set requires a new search.
Saved local preferences
Save a JSON file at ~/.config/japan-rail-mcp/preferences.json, or set
JAPAN_RAIL_PREFERENCES_FILE to its path. The file is read once at startup, so restart the server
after editing it. No MCP tool writes the file. The optional default file may be absent; an
explicitly configured missing file, malformed JSON, unknown setting, or invalid value fails startup
rather than silently ignoring your preferences. Personal settings should stay outside this repository.
{
"defaults": {
"boardingBufferMinutes": 10,
"exitBufferMinutes": 5,
"seatClassId": "reserved"
},
"stations": {
"jp:station:tokyo": {
"boardingBufferMinutes": 15,
"exitBufferMinutes": 10
}
}
}Both planning tools apply built-in defaults → saved global defaults → station-specific
allowances → explicit call values. Only the origin station's boarding allowance and destination
station's exit allowance apply. Global defaults support boardingBufferMinutes,
exitBufferMinutes, maxFareJPY, and seatClassId; station entries support the two allowances.
Explicit zero is respected. Set maxFareJPY: null or seatClassId: null in a call to clear the
corresponding saved restriction. Saved preferences never include travel dates or deadlines.
Use get_personal_preferences to inspect the loaded settings; effective constraints are included
in every comparison result.
Without saved or explicit allowances, the built-in boarding allowance is 10 minutes and the exit allowance is zero. Seat-class matching uses only a total explicitly associated with that class. The Ekispert parser links the selected seat class when its charge matches the charge summary; unselected seat-class prices are not automatically treated as complete fares.
Personal planning without repeated API calls
After search_trains or compare_trains, pass the returned IDs to evaluate_train_options:
{
"trainIds": ["<trainId returned by search_trains>"],
"stationReadyAt": "2026-10-13T11:50:00+09:00",
"boardingBufferMinutes": 10,
"exitBufferMinutes": 8,
"arriveBy": "2026-10-13T16:00:00+09:00",
"maxFareJPY": 15000,
"seatClassId": "reserved"
}The tool checks whether you can reach the departure platform with the specified boarding allowance and finish your destination-station exit allowance by the deadline. It returns feasible options, reasons for excluding other options, cheapest/shortest-ride/earliest-arrival picks, and the cheapest option's savings and arrival delay relative to the earliest option. Change your deadline, budget, or allowances and call it again with zero additional provider requests. Only concise option summaries are returned; full train records need not be sent back.
This comparison uses an in-memory search snapshot in the same server process, retained for
15 minutes and bounded to 200 train records. It does not persist across restarts, refresh the
provider, or fall back to a paid request when an ID is missing/expired. Search again explicitly
to obtain new results. Original provider provenance and retrieval times remain in every option;
evaluatedAt is only the local comparison time. All supplied IDs must share the station pair
and Japan-local departure date. Duplicate IDs are considered once.
The built-in boarding allowance is 10 minutes; the built-in exit allowance is zero. These are
editable personal allowances, not measured station indoor travel times. A requested seat
class requires a total fare explicitly linked to that class. Unknown fares remain null, are
never chosen as cheapest, and are excluded when a budget is specified. Prices do not include
commuter-pass deductions or booking discounts, and seat-class fares do not prove seat availability.
The picks cover only the supplied search candidates, not the whole day's timetable.
get_station_details works without an API key and returns bundled names, operators, prefecture,
Shinkansen lines, and provenance. It does not claim to provide indoor navigation.
Data sources
Bundled station catalog
The project-maintained catalog covers 58 high-value stations: current Shinkansen networks plus a small set of deliberately ambiguous comparison stations such as Osaka, Shinjuku-area stations, and Fukuoka in Toyama. It contains station metadata only—no timetable, fare, or availability data. Operator route maps and travel pages are linked in the source assessment.
Ekispert API
The optional provider uses documented endpoints and a deployment owner's access key. It requests
explicit dates, an explicit midnight when no lower time bound is supplied, stops, seat types, and
operator details. Responses identify ekispert-standard, the endpoint dataset, retrieval time,
realtime status, and the provider-agreement boundary.
Sources not used for Shinkansen timetable data
The current ODPT JR East train-timetable dataset explicitly excludes Shinkansen.
GTFS-JP v4 is a data specification, not a nationwide feed or a blanket data license.
Public JR timetable pages and PDFs do not provide the project with a general-purpose API or a redistribution grant, so they are not scraped or bundled.
See docs/data-sources.md for the dated assessment and primary links.
Architecture
MCP tools
-> RailService
-> StationCatalogProvider
-> StaticShinkansenStationProvider
-> RailDataProvider
-> EkispertProvider (optional key)
core rail schemas
+ Japan extensions
+ provider-private parsing and identifiersMCP handlers validate and describe tool calls but do not fetch or parse provider data. Capability
checks fail closed before network access. search_trains represents a direct physical train;
search_journeys represents an itinerary that may contain transfers. See
docs/architecture.md for the extraction boundary.
Relation to china-rail-mcp
The shared tool names are:
search_stationssearch_trainsget_train_detailsget_availabilitycompare_trains
The common candidate schemas are Station, StationRef, Train, Journey, Fare, SeatClass,
SeatAvailability, Source, RailError, and RailProviderCapabilities. The contract keeps
numeric ISO 4217 fares, explicit country-local time offsets, provenance, canonical station IDs,
provider capability checks, and structured errors.
Japan-specific details live under extensions.japan, including:
Shinkansen lines and service names
provider station names
passenger-facing train numbers versus operational/provider identifiers
Japanese seat labels such as
自由席,指定席,グリーン車, andグランクラス
These boundaries are candidates for a future independent rail-mcp-spec; this repository does not
claim that such a standard already exists.
Limitations
A credential-free install searches stations only.
Live train behavior has fixture-backed contract tests but has not been validated with a real account in this repository. A successful test fixture is not proof of production provider access.
The Ekispert Standard Plan, limits, allowed presentation, commercial use, caching, and redistribution rights depend on the deployment owner's agreement.
Search results are limited to the provider's first 20 answers per request.
search_trainsreturns only direct Shinkansen routes. Transfers are not silently flattened.Seat classes and published fares are not seat inventory.
get_availabilityremains unsupported.Service disruptions and realtime train positions are not included.
The bundled station catalog is Shinkansen-focused, not a complete national station database.
Important travel, fare, and ticket conditions must be checked with the railway operator or an authorized booking channel.
Development
npm install
npm run lint
npm run typecheck
npm test
npm run build
npm run formatTests cover Japanese/English station matching, ambiguity, Tokyo–Shin-Osaka fixture parsing, explicit dates and Tokyo timezone boundaries, provider failures, unsupported availability, MCP structured output, read-only annotations, and a reusable shared rail schema contract.
Security and read-only scope
There are no ticket purchase, reservation, login, payment, CAPTCHA, account, or mutation tools. See SECURITY.md for credential-handling guidance.
License
Project source code is available under the MIT License. That license applies to this repository's code; it does not relicense railway-operator data, Ekispert responses, ODPT datasets, GTFS feeds, or third-party trademarks. Each data source remains subject to its own terms.
Available Tools
7 toolscompare_trainsCompare direct Shinkansen trainsBRead-onlyIdempotent
Use to sort structured direct-train candidates by departure, arrival, duration, or total fare. This tool does not make a subjective recommendation.
Inputs: date (required), toStationId (required), fromStationId (required), limit, +6 more. Returns: limit, total, offset, trains, +3 more
get_availabilityGet seat availabilityARead-onlyIdempotent
Use only to check whether the configured provider exposes seat inventory for an exact train and station pair. The default provider returns an explicit unsupported status and never fabricates inventory.
Inputs: date (required), trainId (required), toStationId (required), fromStationId (required). Returns: seats, reason, source, status, +1 more
get_provider_statusGet rail provider statusARead-onlyIdempotent
Use before live train queries to see which read-only capabilities are configured and why unavailable capabilities are disabled.
Inputs: no named parameters. Returns: notes, provider, configured, capabilities
get_train_detailsGet Shinkansen train detailsARead-onlyIdempotent
Use with the opaque trainId returned by search_trains to retrieve that service and its ordered stops. Do not construct train IDs manually.
Inputs: trainId (required). Returns: stops, train, source
search_journeysSearch transfer journeysARead-onlyIdempotent
Use for routes that may include transfers, not for an individual train. The Shinkansen-first v0.1 provider reports this capability as unsupported rather than returning direct trains under the wrong concept.
Inputs: date (required), toStationId (required), fromStationId (required), operators, +4 more. Returns: journeys
search_stationsSearch Japanese railway stationsARead-onlyIdempotent
Use this before search_trains whenever no canonical station ID is known. Returns candidates for Japanese, English, and common romanized names without silently resolving ambiguous inputs such as Osaka or Fukuoka.
Inputs: query (required), limit. Returns: stations
search_trainsSearch direct Shinkansen trainsARead-onlyIdempotent
Use after resolving both station IDs. Searches direct Shinkansen services only, never transfer journeys. Requires an explicit date; optional time, service, and operator filters are applied before pagination.
Inputs: date (required), toStationId (required), fromStationId (required), limit, +5 more. Returns: limit, total, offset, trains, +3 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a clearly distinct purpose: provider status, station search, direct train search, journey search with transfers, train details, availability check, and comparison. No two tools overlap in function; even search_trains and search_journeys are explicitly separated by transfer handling.
All tool names follow a consistent verb_noun pattern (get_, search_, compare_) with snake_case throughout. The naming is predictable and aligns with the domain verbs expected (get, search, compare).
With 7 tools, the server is well-scoped for a read-only Japan rail information service. Each tool covers a distinct aspect of the domain without unnecessary duplication, fitting the typical 3-15 tool range perfectly.
The tool surface covers the core journey: station lookup, train search (direct and transfers), train details, availability, and comparison. Minor gaps exist like a dedicated fare breakdown or station details, but the essential read-only workflow is fully supported.
Maintenance
Related MCP Connectors
Cached UK train departures and qualified platforms, powered by National Rail Enquiries.
ODPT — Japan rail timetables and live train/service status (Public Transportation Open Data Center).
Deep, obscure Japanese station, accessibility & hazard data for AI agents. English-first.
Read-only public transit departures, stop search, and city coverage for bus and train users.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables route planning and transit information retrieval for Japan using the public Transit API. Supports searching stations, planning routes, and checking departures.102MIT
- AlicenseNot gradedqualityDmaintenanceProvides live UK rail data including station search, departures, arrivals, service details, and pre-filled Trainline booking links.ISC
- AlicenseNot gradedqualityBmaintenanceGives LLM clients structured, read-only access to Indian Railways data: station lookup, timetables, direct trains between stations, station boards, multi-train journeys, punctuality history, and (when a source is configured) seat availability and fares. Every answer carries provenance and cross-source verification status, so results are either real source data or an explicit error code, never fabricated.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables interaction with official Japanese public data, including real-time train service status and live hazard alerts. It provides comprehensive lookups covering station context, accessible toilets, and municipality information.101 npmMIT