japan-rail-mcp

japan-rail-mcp 是一个面向结构化日本铁路数据的只读 Model Context Protocol 服务器。0.1 版本刻意采用**新干线优先（Shinkansen-first）**的设计：它提供一套不含凭据可用的车站目录，并可通过部署所有者的 Ekispert API Standard Plan 密钥查询实时新干线时刻表、票价、座位等级和停靠站。

该服务器不会预订车票、登录铁路账户、绕过访问控制、爬取运营商网站，也不会把测试夹具（test fixtures）当作实时数据展示。

japan-rail-mcp 的设计目标是与 china-rail-mcp 共享一套通用的概念接口，长期目标是建立跨越不同国家的铁路 MCP 服务器之间可互操作的模式。

这是一个实验性的互操作性约定，并不是官方的铁路标准或 MCP 标准。

功能

所有成功返回的数据都附带来源说明。铁路时间戳使用带日本时区偏移的显式 ISO 8601 值，例如 2026-08-26T12:03:00+09:00。类似“明天”这样的相对日期必须由 MCP 客户端解析；服务器要求使用 YYYY-MM-DD。

Related MCP server: DB Timetable MCP Server

MCP 工具

每个工具都被标注为只读、非破坏性和幂等。每个成功的工具结果都包含人类可读的 JSON 文本，以及经过输出模式（schema）校验的 MCP structuredContent。

安装

要求：Node.js 22 或更新版本。CI 使用 Node.js 24 LTS。

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

启动 stdio 服务器：

npm start

在 npm 发布后，客户端也可以这样启动它：

npx -y japan-rail-mcp

实时新干线数据

需要实时时刻表功能，必须具备提供方 Standard Plan 路线搜索端点的访问权限，这取决于部署所有者的 Ek HaS. 免费版方案不含有该核心端点。

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

该密钥只会被发送到配置好的 Ekispert API 端点。它绝不会出现在各工具结果或出现在任一项 provider 错误中。项目中不含共享密钥，不会对 provider 数据的再授权，也不会绕过协议中附带的访问限制。

客户端配置

Claude Desktop

如果是本地 checkout 检查代码，可以添加类似下面的条目，并把其中的绝对路径替换为你自己的路径：

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

如果只做车站搜索，可省略 env。客户端较为稳定的密码管理机制更优于在配置仓库中提交密钥。

Codex

在 Codex 的 MCP 配置中注册已构建的 stdio 命令，或使用你安装的 Codex 版本所支持的 CLI 格式：

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

需要实时列车数据时，应通过进程环境或 Codex 的机密配置提供 EKISPERT_API_KEY。

工具示例

首先解析车站候选人：

{
  "query": "Osaka"
}

在有歧义的情况下，该结果会刻意同时适用于“大阪”（Osaka）和“新大阪”（Shin-Osaka）。然后使用精确的 ID：

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

标准化后的票价是数字且货币安全的类型：

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

formatted 只用于显示；客户端在比较时应使用 amount 与 currency。

数据来源

内置车站目录

项目维护的目录涵盖 58 个高价值车站：包括当前新干线网络，以及一小部分刻意带有歧义的对比车站，如大阪、新宿区域车站和位于富山的直丈「福冈」。该目录只包含车站元数据，不包含时刻表、票价或余票数据。运营商的路线图和旅行页面链接在数据来源评估 中。

Ekispert API

该可选提供方使用 文档化端点 以及部署所有者持有的访问密钥。它会显式请求日期，如果未提供时间下限，则明确请求特定时间、停靠站、座位类型和运营商详情等。响应中标识 ekispert-standard、端点数据集、检索时间、实时状态，以及 provider 协议的相应边界。

不用于新干线时刻表数据的来源

• 当前 ODPT 的 JR East（JR东日本）列车时刻表数据集明确排除新干线。

• GTFS-JP v4 是一种数据规格，而不是全国范围的数据流，也不是全面的数据授权。

• JR 公开的时刻表页面和 PDF 未向本包提供通用 API 或再分发许可，因此既没有抓取，也不会打包。

详见 docs/data-sources.md 中的来源评估。

架构

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

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

MCP 处理器会根据 schema 校验和描述工具调用，但不会真正抓取或解析 provider 数据。能力检查在网络出站之前以 fail-closed 方式失败并拦截。search_trains 表示一列直达的实体列车，而 search_journeys 表示可能包含换乘的行程。关于提取边界，具体信息可参考 docs/architecture.md。

与 china-rail-mcp 的关系

共用的工具名如下：

• search_stations

• search_trains

• get_train_details

• get_availability

• compare_trains

各公共候选模式分别是 Station、StationRef、Train、Journey、Fare 和 SeatClass、SeatAvailability、Source、RailError 以及 RailProviderCapabilities。这个契约保留了紧凑 ISO 4217 的数值型票价、明确的区域本地偏移、来源信息、规范化车站 ID、代码能力检查，以及结构化错误。

日本特有内容则放在 extensions.japan 下面，包括：

• 新干线线路与线路名称

• provider 车站名称

• 面向乘客的列车号与运营/提供方标识符

• 日语座位标签，例如 自由席、指定席、グリーン車 和 グランクラス

以上这些边界可以成为未来独立 rail-mcp-spec 的候选内容，本仓库并不声称这样的规范已存在。

限制

• 无凭据的安装包只能进行车站搜索。

• 实时列车行为已有基于测试夹具（fixture）的契约测试，但本仓库中未用过真实账户进行验证。测试夹具通过不代表生产环境下提供方一定可用。

• Ekispert Standard Plan 及其各自的流动性等边界、允许的表示、商业使用、缓存和再分发权利，需依赖用户与 it its與協議中的条款。

• 每次请求的搜索结果受到限制，最多返回该 provider 已知的前最多 20 项结果。

• search_trains 只返回直达新干线路；换乘不会静默转换或合并。

• 座位等级和公布票价并不等于座位余票；get_availability 依旧不受支持。

• 仅提供定位能力，同时不包含线路中断和实时位置等动态数据。

• 内置车站目录以新干线为中心，并非是日本全国的完整车站数据库。

• 重要旅行、票价以及购票条件必须与铁路运营商或授权渠道核对。

开发

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

测试覆盖了日文・英文车站匹配、歧义、东京 ⇄ 新大阪 fixture 解析、显式日期与东京时区边界、provider 故障、不支持 available、MCP 结构化输出、只读注解，以及可复用的共享 rail schema 契约。

安全性与只读范围

项目不包含任何购票、预订、登录、支付、CAPTCHA、账户或变更修改操作。有关 credential 处理的指南，参见 SECURITY.md。

许可证

本存储库中的源代码均依据 MIT License 发布。该许可证仅适用于本仓库自己的代码，不发生任何对其他数据的再授权，例如不代表对铁路运营方数据、Ekispert 响应、ODPT 数据集、GTFS feed 数据或第三方品牌商标的授权。每个数据源仍然适用其自身的条款。