japan-rail-mcp

japan-rail-mcp es un servidor de solo lectura del Model Context Protocol para datos estructurados del ferrocarril japonés. La versión 0.1 es deliberadamente centrada en el Shinkansen: proporciona un catálogo de estaciones útil sin credenciales y puede consultar horarios en vivo del Shinkansen, tarifas, clases de asiento y paradas mediante una clave del Standard Plan de la API de Ekispert del propietario del despliegue.

El servidor nunca reserva billetes, inicia sesión en cuentas de ferrocarril, elude controles de acceso, extrae datos de sitios web de operadores ni presenta fixtures de prueba como datos en vivo.

japan-rail-mcp está diseñado para compartir una interfaz conceptual común con china-rail-mcp, con el objetivo a largo plazo de establecer esquemas interoperables para servidores MCP de ferrocarril entre países.

Esto es una convención experimental de interoperabilidad, no un estándar oficial ferroviario ni de MCP.

Características

Todos los datos correctos incluyen la procedencia de origen. Los sellos de hora del ferrocarril son valores ISO 8601 explícitos con el desfase de Japón, por ejemplo 2026-08-26T12:03:00+09:00. Las fechas relativas como “mañana” deben ser resueltas por el cliente MCP; el servidor requiere YYYY-MM-DD.

Related MCP server: DB Timetable MCP Server

Herramientas MCP

Cada herramienta está anotada como de solo lectura, no destructiva e idempotente. Cada resultado correcto de la herramienta incluye tanto texto legible JSON por humanos como structuredContent de MCP validado contra un esquema de datos.

Instalación

Requisitos: Node.js 22 o superior. El CI usa Node.js 24 LTS.

git clone https://github.com/TakeruF/japan-rail-mcp.git
cd japan-rail-mcp
npm install
npm run build

Inicie el servidor stdio:

npm start

Después de una publicación en npm, los clientes pueden iniciarlo alternativamente con:

npx -y japan-rail-mcp

Datos en vivo del Shinkansen

La funcionalidad de horarios en vivo requiere una clave de acceso cuyo acuerdo de API de Ekispert incluya el endpoint de búsqueda de rutas del Standard Plan. El plan gratuito no proporciona ese endpoint clave.

export EKISPERT_API_KEY='your-own-key'
npm start

La clave se envía solo al endpoint configurado de la API de Ekispert. Nunca se devuelve en los resultados de las herramientas ni se incluye en los errores de proveedor. El proyecto no incluye una clave compartida, no ofrece sublicencias de los datos del proveedor, ni anula los límites de solicitudes asociados a tu acuerdo.

Configuración del cliente

Claude Desktop

Para una copia local del repositorio, añade una entrada como esta y sustituye la ruta absoluta:

{
  "mcpServers": {
    "japan-rail": {
      "command": "node",
      "args": ["/absolute/path/to/japan-rail-mcp/dist/index.js"],
      "env": {
        "EKISPERT_API_KEY": "your-own-key"
      }
    }
  }
}

Omite el objeto env si solo necesitas la búsqueda de estaciones. Prefiere el gestor de secretos de tu cliente en lugar de guardar claves en un repositorio de configuración.

Codex

Registra el comando stdio compilado con la configuración MCP de Codex, o usa el formato CLI que admita tu versión instalada de Codex:

codex mcp add japan-rail -- node /absolute/path/to/japan-rail-mcp/dist/index.js

Proporciona EKISPERT_API_KEY a través del entorno del proceso o de la configuración de secretos de Codex cuando se requieran datos en vivo de los trenes.

Ejemplos de herramientas

Primero, resuelve los candidatos de estación:

{
  "query": "Osaka"
}

El resultado incluye deliberadamente tanto Osaka como Shin-Osaka cuando sea pertinente. Después usa los ID exactos:

{
  "fromStationId": "jp:station:tokyo",
  "toStationId": "jp:station:shin-osaka",
  "date": "2026-08-26",
  "departureAfter": "12:00",
  "serviceTypes": ["shinkansen"],
  "limit": 10,
  "offset": 0
}

Una tarifa normalizada es numérica y segura para monedas:

{
  "amount": 14720,
  "currency": "JPY",
  "formatted": "¥14,720",
  "kind": "total"
}

formatted es solo para mostrar; los clientes deben usar amount y currency para comparar.

Fuentes de datos

Catálogo de estaciones incluidas

El catálogo mantenido por el proyecto cubre 58 estaciones de alto valor: las redes Shinkansen actuales más un pequeño conjunto de estaciones comparativas deliberadamente ambiciosas, como descartes, estaciones de la zona de Shinjuku y Fukuoka en Toyama. Solo contiene metadatos de estación—sin datos de horarios, tarifas ni disponibilidad. Los mapas de rutas del operador y las páginas web de viajes se incluyen en la evaluación de fuentes.

API de Ekispert

El proveedor opcional usa endpoints documentados y una clave de acceso del propietario del despliegue. Solicita fechas explícitas, una medianoche explícita cuando no se proporciona un límite de hora inferior, paradas, tipos de asiento y detalles del operador. Las respuestas identifican ekispert-standard, el conjunto de datos del endpoint, el tiempo de recuperación, el estado en tiempo real y el límite del acuerdo del proveedor.

Fuentes no utilizadas para la base de Step

El conjunto de datos de horarios de ODPT JR East actual excluye explícitamente el Shinkansen. GTFS-JP v4 es una especificación de datos, no una fuente nacional de datos ni una licencia de datos general. Las páginas públicas de horarios y los PDF de JR no proporcionan al proyecto una API de propósito general ni una autorización de redistribución, por lo que no se analizan ni se incluyen.

Consulta docs/data-sources.md para la evaluación con fecha y los enlaces originales.

Arquitectura

MCP tools
  -> RailService
    -> StationCatalogProvider
       -> StaticShinkansenStationProvider
    -> RailDataProvider
       -> EkispertProvider (optional key)

core rail schemas
  + Japan extensions
  + provider-private parsing and identifiers

Los manejadores de MCP valigan y describen las llamadas a las herramientas pero no obtienen ni parsean datos del proveedor. Las comprobaciones de capacidad fallan de manera cerrada antes del acceso a la red. search_trains representa una tren físico directo; search_journeys representa un itinerario que puede contener transbordos. Consulta docs/architecture.md para conocer el límite de extracción.

Relación con china-rail-m

Los nombres de herramientas compartidos:

• search_stations

• search_trains

• get_train_details

• get_availability

• compare_trains

Los esquemas de datos candidatos comunes son Station, StationRef, Train, Journey, Fare, SeatClass, SeatAvailability, Source, RailError y RailProviderCapabilities. El contrato mantiene tarifas numéricas ISO 4217, desfases horarios locales explícitos, la procedencia, los ID de estación normales, las comprobaciones de capacidades del proveedor y los errores estructurados.

Los detalles específicos de Japón viven en extensions.japan, incluyendo:

• Líneas y nombres de servicios del Shinkansen

• Nombres de estaciones del proveedor

• Números de tren visibles para los pasajeros frente a identificadores operativos/de proveedor

• Etiquetas japonesas de asiento como 自由席, 指定席, グリーン車 y グランクラス

Estos límites son candidatos para un futuro rail-mcp-spec independiente; este repositorio no afirma que such standardzo ya existe.

Limitaciones

• Una instalación sin credenciales solo deja buscar estaciones.

• El comportamiento en vivo de los vagones tiene pruebas de contrato con datos de prueba, pero no se ha validado con una cuenta real en este repositorio. Una prueba de fixture exitosa no es prueba móvil de acceso al proveedor de producción.

• El acceso al Standard Plan, los límites, la presentación permitida, el uso comercial, las cachés y los derechos de redistribución dependen del acuerdo del propietario del despliegue.

• Los resultados de búsqueda se limitan a las primeras 20 respuestas del proveedor por solicitud.

• search_trains solo devuelve rutas directas de Shinkansen. Los transbordos no se ocultan.

• Las clases de asiento y las tarifas publicadas no son inventario de asientos. get_availability sigue sin ser compatible.

• Las interrupciones de servicio y las posiciones de trenes en tiempo real no están incluradas.

• El catálogo de estaciones es centrado en el Shinkansen, no es una base de datos nacional completa.

• Es necesario revisar con el operador ferroviario o un canal de reserva autorizado las condiciones, tarifas y billetes importantes.

Desarrollo

npm install
npm run lint
npm run typecheck
npm test
npm run build
npm run format

Las pruebas cubren coincidencia de estaciones en japonés/inglés, ambigüedad, análise de la fondo de Tokyo-Shin-Osaka, fechas explícitas y límites de la zona horaria de Tokio, fallos del proveedor, no disposición de disponibilidad, mismo resultado estructurado de MCP, anotaciones de solo lectura y un contrato compartido de rawaya reusable.

Seguridad y alcance de solo lectura

No hay herramientas de compra de billetes, reservas, inicio de sesión, payment, CAPTCHA, cuenta o mutación. Consulta SECURITY.md para conocer las recomendaciones de gestión de credenciales.

Licencia

El código fuente del proyecto se ofrece bajo la Licencia MIT. Esa licencia se aplica al código de este espacio; no tiene re­licencia ninguna de los datos del operador ferroviario, respuestas de Ekispert, conjuntos de datos ODPT, feeds OP, ni marcas comerciales de terceros. Cada fuente de datos sigue sujeta a sus propios términos.