japan-rail-mcp

japan-rail-mcp는 구조화된 일본 철도 데이터를 위한 읽기 전용 Model Context Protocol 서버입니다. 버전 0.1은 의도적으로 **신칸센 우선(Shinkansen-first)**입니다. 즉, 자격 증명 없이 쓸 수 있는 역 카탈로그를 제공하며, 배포 소유자의 Ekispert API Standard Plan 키를 통해 실시간 신칸센 시간표, 요금, 좌석 등급, 정차역을 조회할 수 있습니다.

이 서버는 티켓을 예매하거나 철도 계정에 로그인하지 않으며, 접근 제어를 우회하지 않고, 운영사 웹사이트를 스크래핑하지 않으며, 테스트 픽스처를 실시간 데이터로 제시하지 않습니다.

japan-rail-mcp는 china-rail-mcp와 공통된 개념적 인터페이스를 공유하도록 설계되었으며, 장기적으로는 국가 간 철도 MCP 서버들의 상호운용 가능한 스키마를 확립하는 것을 목표로 합니다.

이것은 실험적 상호운용성 협약이며, 공식 철도 표준이나 MCP 표준이 아닙니다.

주요 기능

All successful data includes 출처(provenance). 철도 시간 표시는 일본 오프셋이 포함된 명시적 ISO 8601 값입니다(예: 2026-08-26T12:03:00+09:00). “내일”과 같은 상대 날짜는 클라이언트에서 결정해야 합니다. 서버는 YYYY-MM-DD 형식을 요구합니다.

Related MCP server: DB Timetable MCP Server

MCP 도구

모든 도구는 읽기 전용이며, 비파괴적이고, 멱등(idempotent)입니다. 성공적인 도구 결과에는 사람이 읽을 수 있는 JSON 텍스트와 출력 스키마로 검증된 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

신칸센 실시간 데이터

실시간 시간표 기능은 Ekispert API 계약에 Standard Plan 경로 검색 엔드포인트가 포함된 액세스 키가 있어야 합니다. 무료 요금제에서는 이 핵심 엔드포인트를 제공하지 않습니다.

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

키는 설정된 Ekispert API 엔드포인트로만 전송됩니다. 도구 결과나 공급자 오류에는 절대 포함되지 않습니다. 이 프로젝트에는 공용 키가 없으며, 공급자 데이터를 재라이선스하지 않고, 계약에 명시된 요청 한도를 변경하지 않습니다.

Claude Desktop

로컬 체크아웃을 사용하는 경우 다음 항목을 추가하고 절대 경로를 교체하세요:

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

Stations 검색 전용인 경우에는 env 객체를 생략하세요. 키를 설정 저장소에 커밋하기보다 클라이언트의 비밀 관리 기능을 우선 사용하는 것이 좋습니다.

Codex

빌드된 stdio 명령을 Codex의 MCP 설정에 등록하거나 설치된 Codex 버전에서 지원하는 CLI 형식을 사용하세요:

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

실시간 열차 데이터가 필요하면 EKISPERT_API_KEY를 프로세스 환경이나 Codex의 비밀 설정을 통해 제공하세요.

도구 사용 예시

먼저 역 후보를 확인합니다:

{
  "query": "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

선택 제공자는 문서화된 엔드포인트와 배포 소유자의 액세스 키를 사용합니다. 요청 시 명시적 날짜, 하한 시각이 제공되지 않은 경우 명시적 자정(00:00), 정차역, 좌석 유형, 사업자 세부 정보를 요청합니다. 응답에는 ekispert-standard, 엔드포인트 데이터셋, 조회 시각, 실시간 상태, 공급자 계약 경계가 표시됩니다.

신칸센 시간표 데이터에 사용하지 않는 출처

• 현재 ODPT JR East 열차 시간표 데이터셋은 신칸센을 명시적으로 제외합니다.

• 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 핸들러는 도구 호출을 검증하고 설명하지만 공급자 데이터를 가져오거나 파싱하지 않습니다. 기능 확인은 네트워크 접근 전에 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 아래 있으며, 다음을 포함합니다:

• 신칸센 노선 및 서비스 이름

• 공급자가 표기하는 역명

• 승객 대상 열차 번호와 운영 / 제공자 식별자 구분

• 自由席, 指定席, グリーン車, グランクラス 같은 일본 좌석 라벨

이러한 경계는 미래의 rail-mcp-spec 후보입니다. 지금 이미 존재하는 표준이라고 주장하지는 않습니다.

제한 사항

• 자격 증명 없이 설치하면 역에서 역 검색만 됩니다.

• 실시간 열차 동작은 픽스처 기반 계약 시험만 존재하며, 본 저장소에서 실제 계정으로 수행되지는 않았습니다. 테스트 픽스 처 가 통과해도 프로덕션 공급자 접근을 보증하지 않습니다.

• Ekispert Standard Plan의 한도, 결과 표현 방식, 상업적 이용, 캐싱, 재배포 권한은 모두 배포 소유자의 계약에 따라 차이가 있습니다.

• 검색 결과는 요청당 제공자의 첫 20개 응답으로 제한됩니다.

• search_trains는 직행 신칸센 노선만 반환하며, 환승 구간을 억지로 직행으로 변환하지 않습니다.

• 좌석 등급과 게시 요금은 좌석 재고가 아닙니다. get_availability는 여전히 미지원 상태입니다

• 지연 운행과 실시간 열차 위치는 제공되지 않습니다.

• 포함된 역 카탈로그는 신간센 중심이라 전국 역이라기보다는 특화되어 있습니다.

• 중요한 여행 정보, 요금, 티켓 조건은 철도 운영사나 공식 예약 채널을 통해 확인 해야 합니다.

개발

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

테스트는 일본어/영어 역명 매칭, 명칭 혼돈 가능성, 도쿄–신타오사카 픽스처 파싱, 명시 날짜 및 도쿄 시간대 경계, 공급자 오류, 미지원 가용성, MCP 구조적 출력, 읽기 전용 주석, 공용 철도 스키마 계약을 다룹니다.

보안 및 읽기 전용 범위

티켓 구매, 예약, 로그인, 결제, CAPTCHA, 계정, 데이터 변환과 같은 도구는 없습니다. 자격 증명 처리 지침은 SECURITY.md를 참고하세요.

라이선스

프로젝트 소스 코드는 MIT 라이선스로 제공됩니다. 이 라이선스는 이 저장소 코드에 적용되며, 철도 운영사 데이터, Ekispert 응답, ODPT 데이터셋, 는 GTFS 피드, 제3자 상표를 재라이선스하지 않습니다. 각 데이터 소스는 고유의 이용 약관을 따릅니다. - Relay을 반환한다: