Korea MCP

korea-mcp 🇰🇷

English · 한국어

AI エージェントが韓国を移動できるようにします。 Claude、Cursor、ChatGPT、あらゆる MCP クライアントで使える MCP サーバーとして、英語での地下鉄ルート、運賃、祝日、実用的なヒントを提供します。

API キー不要。韓国の電話番号不要。オフラインでも動作します。

You:    How do I get from Myeongdong to Seongsu by subway?

Agent:  Take Line 4 from Myeongdong (명동) on the platform whose next stop is
        Chungmuro (충무로). Ride 2 stops to Dongdaemun History & Culture Park.
        Transfer to Line 2 towards Sindang (신당) and ride 6 stops to Seongsu (성수).
        About 22 minutes, ₩1,550 with a T-money card.

韓国では Google マップが役に立たない理由

韓国を訪れたことがある方ならご存じでしょう。Google マップでは、ここで徒歩や車のルートを検索できず、公共交通機関の検索結果も不完全なことがよくあります。韓国では地図データの国外持ち出しが制限されているため、現地の人は Naver Map や KakaoMap を使っています。

人間には問題ありませんが、AI エージェントには困りものです。Naver と Kakao は公共交通機関の経路検索 API を公開しておらず、その他の API の利用には韓国の開発者アカウントが必要です。そのため、AI に「聖水へはどう行けばいい？」と尋ねても、推測で答えることになります。

korea-mcp は、パッケージに同梱されたオープンデータで基本的な機能を提供します。

• ソウル、仁川、京畿道の25路線にある660駅。駅名は英語、韓国語、日本語、中国語に対応
• 乗り換え、ホームの方向、所要時間の目安を考慮したルート検索
• 公式の距離制運賃計算式
• 代替休日を含む韓国の祝日
• T-money、空港への移動、緊急電話番号、利用可能なアプリに関する簡潔で実用的なガイド

インストール

Claude Code

claude mcp add korea -- npx -y korea-mcp

Claude Desktop、ワンクリック。 korea-mcp.mcpb をダウンロードして開きます。Claude Desktop が拡張機能としてインストールします。

Claude Desktop（手動）、Cursor、その他の MCP クライアント。 MCP 設定（claude_desktop_config.json、.cursor/mcp.json、…）に次を追加します。

{
  "mcpServers": {
    "korea": {
      "command": "npx",
      "args": ["-y", "korea-mcp"]
    }
  }
}

Node.js 20 以降が必要です。

ツール

ツール	機能
subway_route	2つの駅の間のルートを検索します。路線、乗り換え、利用するホーム、停車駅数、所要時間、運賃を確認できます。英語、한국어、日本語、中文、ランドマーク名（「Hongdae」「COEX」「Incheon Airport T1」）に対応しています。タイプミスも許容します。
subway_station	駅名を検索して翻訳します。すべての言語での駅名、乗り入れ路線、座標を返します。
korea_holidays	指定期間内の祝日を確認したり、「この日は祝日ですか？」と尋ねたりできます。代替休日と、2026年に追加された祝日（勤労者の日、憲法記念日）も含まれます。
korea_guide	実用ガイド：transit-card、airport、emergency、apps。

質問例

• 「午後9時に仁川第2ターミナルに到着します。弘大近くのホテルにはどう行けばいいですか？」
• 「江南から景福宮まで最速で行くにはどうすればいいですか？運賃はいくらですか？」
• 「2026年9月24日の週、韓国で休業するところはありますか？」
• 「T-money カードにチャージするにはどうすればいいですか？」
• 「을지로입구 は英語で何という意味ですか？どの路線が停車しますか？」

精度

このサーバーが把握している情報と、推定している情報は以下のとおりです。

• 駅の順序と乗り換えはOpenStreetMapに基づいており、信頼できます。
• 所要時間は推定値です。 距離、路線の速度、乗り換え1回あたり約7分に基づき、公開されている所要時間に合わせて調整しています。リアルタイムの時刻表はありません。
• 運賃は、大人向けの公式な距離制運賃計算式（カード利用時の基本運賃₩1,550、2025-06-28適用）を使用します。独自の追加料金がある路線（Shinbundang、AREX、GTX-A）は、合計金額には加算せず、レスポンス内に表示します。
• 急行列車は、OSMの急行停車パターンが不完全なため、デフォルトでは無効です。allow_expressで有効にできます。

間違った経路を見つけましたか？ 駅を2つ記載してイシューを作成してください。これが最も役に立つバグ報告です。

korea-mcpが移動に役立ったなら、⭐を付けていただけると、ほかの旅行者にも見つけてもらいやすくなります。

ロードマップ

以下は無料のAPIキーが必要な、導入予定の任意の追加機能です。上記の機能はすべて、これらがなくても動作します。

• リアルタイムの列車到着情報（Seoul Open Data）
• Kakao Local APIによる場所検索（「聖水周辺のカフェ」「今営業中の薬局」）
• ODsayによるバスとドア・ツー・ドアの経路検索
• インストール不要のホスト型リモートサーバー
• 釜山、大邱、大田、光州の地下鉄
• 長期滞在向けガイド：ARC、銀行口座、携帯電話プラン、健康保険

キーの仕組みについては、docs/api-keys.mdをご覧ください。

開発

npm install
npm test              # route, fare and holiday tests
npm run dev           # run the server with tsx
npm run data:subway   # rebuild data/subway.json from OpenStreetMap

地下鉄データセットは、OpenStreetMapのルートリレーションからscripts/build-subway.mjsで生成されます。路線の定義と名称の上書き設定は、このスクリプトに記載されています。速度モデルはsrc/subway/route.tsにあります。

どの言語での貢献も歓迎します。韓国語でのイシューやPRも問題ありません。

クレジットと関連プロジェクト

この分野の一部を先行して開拓したプロジェクトです。ぜひスターを付けてください。

• naeryeo：ODsayを使用した韓国の交通経路検索CLIおよびMCP
• seoul-essentials：ソウルを訪れる外国人向けの公共施設情報
• kakao-navigation-mcp-server、mcp-server-kakao-map、およびNaver MapsのMCPサーバー
• awesome-mcp-korea：韓国のMCPサーバーの一覧

ライセンス

コードはMITライセンスです。地下鉄データは© OpenStreetMap contributorsに帰属し、ODbL 1.0に基づいています。

---

한국어

English · 한국어

外国人の友人がAIに「明洞から聖水へはどう行けばいい？」と尋ねたとき、ちゃんとした答えが返ってくるようにするMCPサーバーです。

地下鉄の経路や運賃、祝日、生活情報を英語・韓国語・日本語・中国語で案内します。Claude、Cursor、ChatGPTなど、MCPに対応するあらゆるAIエージェントで使えます。

APIキーも韓国の携帯電話番号も不要で、オフラインで動作します。

作成した理由

韓国では、Googleマップで徒歩や自動車の経路検索ができず、公共交通機関の情報も不正確な場合が多くあります。地図データの国外持ち出しが制限されているためです。そのため、韓国の人々はNaver MapやKakaoMapを使っています。

しかし、これはAIエージェントにとって問題です。NaverとKakaoは公共交通機関の経路検索APIを外部に公開しておらず、ほかのAPIも韓国の開発者アカウントがないと利用できません。その結果、AIは経路をでっち上げてしまいます。

korea-mcpは、公開データをパッケージに内蔵することでこの問題を解決します。

• 首都圏（ソウル・仁川・京畿道）の25路線、660駅と4言語の駅名
• 乗り換え、乗車するホームの方向、所要時間の目安を案内する経路検索
• 公式の距離制運賃計算
• 振替休日を含む韓国の祝日
• T-money、空港への移動、緊急電話、韓国で役立つアプリの案内

インストール

Claude Code

claude mcp add korea -- npx -y korea-mcp

Claude Desktopへのワンクリックインストール。 korea-mcp.mcpbをダウンロードして開くと、Claude Desktopの拡張機能としてインストールされます。

Claude Desktop（手動設定）、Cursorなど。 MCP設定ファイルに以下の内容を追加してください。

{
  "mcpServers": {
    "korea": {
      "command": "npx",
      "args": ["-y", "korea-mcp"]
    }
  }
}

Node.js 20以上が必要です。

ツール

ツール	機能
subway_route	2駅間の経路：路線、乗換駅、乗車するホーム、停車駅数、所要時間の目安、運賃。英語・韓国語・日本語・中国語の駅名やランドマーク（「Hongdae」「COEX」）を認識し、入力ミスにも対応します。
subway_station	駅の検索と駅名の翻訳。各言語の駅名、乗り入れ路線、座標を案内します。
korea_holidays	指定期間内の祝日を検索し、特定の日付が祝日かどうかを確認します。振替休日と、2026年に新たに加わった労働者の日・憲法記念日も含みます。
korea_guide	生活ガイド：transit-card（交通カード）、airport（空港）、emergency（緊急電話）、apps（アプリ）

정확도

• 역 순서와 환승 정보는 OpenStreetMap 기반이라 신뢰할 수 있습니다.
• 소요 시간은 추정치입니다. 역 간 거리, 노선별 속도, 환승 약 7분으로 계산하고 공개된 소요 시간에 맞춰 보정했어요. 실시간 시간표는 아닙니다.
• 요금은 2025년 6월 28일부터 적용된 수도권 통합 거리비례제(교통카드 성인 기본 1,550원)를 따릅니다. 신분당선, 공항철도, GTX-A처럼 별도 요금이 붙는 노선은 응답에 안내만 하고 합계에는 넣지 않습니다.
• 급행은 기본으로 꺼져 있습니다. OSM의 급행 정차 정보가 불완전하기 때문이에요. 쓰려면 allow_express 옵션을 켜세요.

틀린 경로를 발견하면 출발역과 도착역을 적어서 이슈로 알려주세요. 가장 도움이 되는 제보입니다.

도움이 됐다면 ⭐ 하나 눌러 주세요. 다른 여행자들이 이 프로젝트를 찾는 데 큰 도움이 됩니다.

로드맵

아래 기능은 무료 API 키가 있으면 쓸 수 있는 선택 기능으로 추가할 예정입니다. 키가 없어도 기존 기능은 그대로 동작해요.

• 실시간 지하철 도착 정보 (서울 열린데이터광장)
• 장소 검색 ("성수 근처 카페", "지금 문 연 약국"), 카카오 로컬 API 사용
• 버스를 포함한 출발지→도착지 경로 (ODsay)
• 설치 없이 쓰는 원격 서버
• 부산·대구·대전·광주 도시철도
• 장기 체류자용 가이드: 외국인등록증, 은행 계좌, 휴대폰 개통, 건강보험

키 사용 방식은 docs/api-keys.md를 참고하세요.

개발

npm install
npm test              # 경로·요금·공휴일 테스트
npm run dev           # tsx로 서버 실행
npm run data:subway   # OpenStreetMap에서 data/subway.json 다시 생성

이슈와 PR은 한국어로 남기셔도 됩니다. 영어 역명 오류, 빠진 노선, 가이드 내용 보완 같은 기여를 특히 환영해요.

참고 프로젝트

이 분야를 먼저 다룬 프로젝트들입니다. 위의 Credits 목록을 참고하세요.

라이선스

코드는 MIT, 지하철 데이터는 © OpenStreetMap contributors이며 ODbL 1.0을 따릅니다.