korail-mcp

🇰🇷 한국어 · 🇬🇧 English

KORAIL 공공데이터 MCP

한국철도공사(KORAIL) 공공데이터를 AI에 연결하는 MCP(Model Context Protocol) 서버 모음입니다. 설치 후 Claude Desktop·Claude Code·Cursor·Antigravity·GitHub Copilot(CLI/VS Code) 등에서 자연어로 KORAIL 데이터를 조회할 수 있습니다.

✅ API 키 신청 불필요 — 전용 프록시 서버가 공공데이터 API 호출을 대신 처리합니다.

💻 로컬 설치형 (stdio) — 별도 서버 없이 개인 PC에서 직접 실행됩니다. Claude Desktop·Claude Code·Cursor·Antigravity·GitHub Copilot(CLI/VS Code) 등 로컬 MCP 클라이언트에 연결합니다. ChatGPT·Grok 같은 웹 서비스는 원격 연결이 필요합니다(하단 "그 밖의 방식" 참고).

📦 필요 디스크 공간 — 약 100MB (uv가 관리하는 Python과 패키지 포함)

👉 처음이신가요? 바로 아래 "제일 쉬운 방법"부터 시도해보세요. 98개 도구 전체 목록은 설치를 마친 뒤 필요할 때 참고하세요.

🤖 제일 쉬운 방법 — AI에게 그대로 시키기

Claude Code·Cursor·GitHub Copilot(CLI/VS Code)·Antigravity처럼 터미널 명령을 직접 실행할 수 있는 AI를 쓰고 있다면, 그 채팅창에 아래 문장을 그대로 붙여넣으세요.

https://github.com/lovelyquality/korail-mcp 의 README를 참고해서 이 MCP 서버를 설치하고 내 클라이언트에 연결해줘.

AI가 README를 직접 읽고 uv 설치 → korail-mcp 설치 → 클라이언트 설정 파일 등록까지 알아서 처리합니다. 완료되면 "서울역에 엘리베이터가 있나요?" 같은 질문으로 확인해보세요.

⚠️ ChatGPT·Grok처럼 로컬 명령을 실행하지 못하는 AI에서는 이 방법이 통하지 않습니다(왜인지는 하단 "그 밖의 방식" 참고). 그리고 AI가 중간에 막히거나, 애초에 이런 방식의 AI 도구가 없다면 → 바로 아래 "수동 설치"를 그대로 따라 하시면 됩니다.

⚙️ 수동 설치 (Windows · 2단계)

Python을 따로 설치하거나 저장소를 다운로드할 필요가 없습니다. uv가 필요한 것을 알아서 준비합니다.

1단계 — uv 설치 (최초 1회)

PowerShell을 열고 아래를 붙여넣습니다. 관리자 권한이 필요 없습니다.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

설치 후 PowerShell을 새로 열고 uv --version이 출력되면 성공입니다.

2단계 — KORAIL MCP 설치 (최초 1회)

uv tool install --from git+https://github.com/lovelyquality/korail-mcp.git korail-mcp

마지막에 Installed 1 executable: korail-mcp 가 나오면 성공입니다.

⏳ 첫 설치는 1~3분 걸립니다(Python과 패키지를 받는 시간). 설치 후 실행은 약 5초입니다.

🔄 최신 버전으로 갱신 — uv tool upgrade korail-mcp 실행 후 클라이언트를 재시작하세요.

⚠️ 갱신 전에는 korail-mcp를 쓰는 클라이언트(Claude Desktop·Cursor·Antigravity·VS Code 등)를 먼저 완전히 종료하세요. 실행 중인 상태로 갱신하면 실행파일이 잠겨 있어 내부 패키지만 새 버전으로 바뀌고 실행파일은 그대로 남아 ModuleNotFoundError: No module named 'gateway'로 깨질 수 있습니다 (2026-08-24 실측으로 재현·확인). 이미 이 에러가 나면 korail-mcp.exe를 쓰는 모든 프로세스를 작업 관리자에서 종료한 뒤 uv tool install --from git+https://github.com/lovelyquality/korail-mcp.git korail-mcp --force로 재설치하세요. 여러 클라이언트가 같은 설치를 동시에 쓰는 것 자체는 문제 없습니다 — 충돌은 갱신하는 그 순간에만 일어납니다.

🔌 3단계 — 클라이언트 연결

아래 JSON을 클라이언트 설정 파일의 mcpServers 안에 넣고, <사용자명> 부분만 본인 윈도우 계정명으로 바꿉니다.

{
  "mcpServers": {
    "korail-mcp": {
      "command": "C:\\Users\\<사용자명>\\.local\\bin\\korail-mcp.exe"
    }
  }
}

💡 계정명을 모르면 PowerShell에 echo $env:USERNAME 을 입력하세요. 경로의 역슬래시는 JSON 규칙상 두 개(\\) 로 씁니다.

⚠️ 이미 다른 MCP 서버를 쓰고 있다면 korail-mcp 항목만 기존 mcpServers 안에 추가하세요(전체를 덮어쓰면 기존 서버가 사라집니다).

設定ファイルの場所

# 1) korail-mcp를 MCP 서버로 등록 (최초 1회)
claude mcp add korail-mcp -s user -- "C:\Users\<사용자명>\.local\bin\korail-mcp.exe"

# 2) 실제 질문 (해당 도구만 허용)
claude -p "korail-mcp 도구를 사용해서 서울역에 엘리베이터가 있는지 알려줘" --allowedTools "mcp__korail-mcp__*"

# 1) 설치 (최초 1회)
npm install -g @github/copilot

# 2) korail-mcp를 MCP 서버로 등록 (최초 1회)
copilot mcp add korail-mcp -- "C:\Users\<사용자명>\.local\bin\korail-mcp.exe"

# 3) 실제 질문 (도구 자동 승인)
copilot -p "서울역에 엘리베이터가 있는지 korail-mcp 도구로 조회해줘" --allow-all-tools

{
  "servers": {
    "korail-mcp": {
      "command": "C:\\Users\\<사용자명>\\.local\\bin\\korail-mcp.exe"
    }
  }
}

接続後に必ず行うこと — クライアントを完全に終了してから再起動

ℹ️ Claude Code・GitHub Copilot CLI ではこの手順は不要です — コマンドを実行するたびに設定を読み込み直します。以下は Claude Desktop・Cursor・Antigravity・VS Code のように、ウィンドウを開いたまま使うクライアントのみが対象です。

ウィンドウの X をクリックして閉じても、トレイ（タスクバー右側の ^ の中）では引き続き実行中のため、設定が適用されません。 → トレイアイコンを右クリック → Quit / 終了してから再起動してください。

正常に接続されると、設定の MCP サーバー一覧に korail-mcp が running と表示され、98 個のツールを使えるようになります。

💬 インストールの確認 — 次のように聞いてください

서울역에 엘리베이터가 있나요?
2024년 간선철도 수송실적을 알려주세요.
KTX 101 열차의 운행 계획을 알려주세요.

正常な応答が返れば、インストール完了です。さらに多くの使用例については、ドキュメント下部の「使用例」セクションを参照してください。

📦 제공 서버 (총 11개 · 98개 도구)

서버별 도구 상세 (클릭하여 펼치기)

🧩 그 밖의 방식

{
  "mcpServers": {
    "korail-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/lovelyquality/korail-mcp.git", "korail-mcp"]
    }
  }
}

git clone https://github.com/lovelyquality/korail-mcp.git
cd korail-mcp
uv run gateway/server.py

💬 사용 예시

서울역에 엘리베이터가 있나요?                     (convenience)
2026년 4월 KTX 발권유형 비율을 알려주세요.        (stats)
KTX 101 열차의 운행 계획을 알려주세요.            (train-ops)
서울역 코드가 뭔가요?                             (codebook)
2024년 간선철도 수송실적을 알려주세요.            (stats)
컨테이너 화물 운송 이력을 조회해주세요.           (freight)
경부선 KTX 정차역과 역간 거리를 알려주세요.       (network)
KTX 차량 형별 제원을 보여주세요.                  (rolling-stock)
철도 고객센터 상담유형 코드를 알려주세요.         (voc-cs)
역사 임대매장 현황을 알려주세요.                  (internal-svc)
'EMU용품' 자재그룹코드를 검색해주세요.            (procurement)
강남역(서울교통공사) 엘리베이터 위치를 알려주세요.  (urban-rail)
서울역 도시철도 역사들의 운영기관을 찾아주세요.    (urban-rail)

📚 데이터 출처

• 한국철도공사 공공데이터포털 (data.go.kr)
• 국가철도공단(KRIC) 철도산업정보센터 오픈API (openapi.kric.go.kr) — 도시철도 역사정보
• REST API(B551457) · odcloud 파일변환 API · 로컬 CSV

⚠️ 주의사항

• 데이터 호출은 전용 Cloudflare Workers 프록시를 경유하므로 직원 개인 API 키가 필요 없습니다.
• 각 데이터셋의 기준일·갱신주기는 도구 응답의 _meta 항목에 표시됩니다.

각 서버의 상세 동작은 해당 폴더의 server.py docstring을 참조하세요.