Korea MCP

korea-mcp 🇰🇷

英语 · 한국어

让你的 AI Agent 带你畅游韩国。 通过适用于 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 Maps 在韩国不好用

如果你去过韩国，就会知道：Google Maps 无法在这里提供步行或驾车路线，公共交通路线也经常不完整。韩国限制导出地图数据，因此当地人使用 Naver Map 和 KakaoMap。

这对人来说没问题，但对 AI Agent 来说就不行了。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	查询两个车站之间的路线：线路、换乘、应乘坐的站台、站数、耗时和票价。支持英语、한국어、日本語、中文和地标（“Hongdae”“COEX”“Incheon Airport T1”）。支持模糊匹配拼写错误。
subway_station	查询并翻译车站名称。返回所有语言的名称、停靠线路和坐标。
korea_holidays	查询指定日期范围内的公休日，或询问“这一天是假日吗？”。包括替代公休日和 2026 年新增的假日（劳动节、宪法日）。
korea_guide	实用指南：transit-card、airport、emergency、apps。

可以这样提问

• “我晚上 9 点到仁川机场 T2。怎么去弘大附近的酒店？”
• “从江南到景福宫最快怎么走？要多少钱？”
• “2026 年 9 月 24 日那一周，韩国有没有什么地方会关门？”
• “T-money 卡怎么充值？”
• “을지로입구 用英语是什么意思？哪些线路会停靠那里？”

准确性

以下是此服务掌握的信息，以及仅为估算的信息：

• 站点顺序和换乘信息来自 OpenStreetMap，可靠。
• 乘车时间为估算值。 根据距离、线路速度和每次换乘约 7 分钟计算，并参照已公布的行程时间进行校准。没有实时班次信息。
• 票价采用成人官方一体化距离计费公式（使用交通卡时起步价为 ₩1,550，自 2025-06-28 起生效）。有单独附加费用的线路（Shinbundang、AREX、GTX-A）会在响应中标记，但不会计入总价。
• 快速列车默认关闭，因为 OSM 中快速列车的停站模式信息不完整。使用 allow_express 可开启。

发现错误路线？请提交问题并附上两个站点。这是最有帮助的错误报告。

如果 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

地铁数据由 scripts/build-subway.mjs 根据 OpenStreetMap 路线关系生成。线路定义和名称覆盖项位于该脚本中。速度模型位于 src/subway/route.ts。

欢迎使用任何语言贡献。也欢迎用韩语提交问题和 PR。

致谢与相关项目

这些项目率先探索了该领域的部分方向。欢迎给它们点个星：

• naeryeo：使用 ODsay 的韩国交通路线规划命令行工具和 MCP
• seoul-essentials：为首尔外国访客提供的公共设施信息
• kakao-navigation-mcp-server、mcp-server-kakao-map 和 Naver Maps MCP 服务
• awesome-mcp-korea：韩国 MCP 服务列表

许可证

代码采用 MIT 许可证。地铁数据 © OpenStreetMap 贡献者，遵循 ODbL 1.0 许可。

---

한국어

English · 한국어

这是一个 MCP 服务，能让外国朋友问 AI“从明洞怎么去城水？”时，得到正确的答案。

它以英语、韩语、日语和中文提供地铁路线和票价、公共假日及生活信息。可用于 Claude、Cursor、ChatGPT 等所有支持 MCP 的 AI Agent。

无需 API 密钥或韩国手机号，也可离线运行。

为什么要开发

在韩国，无法使用 Google 地图规划步行和驾车路线，公共交通信息也常常不准确。这是因为地图数据受到境外转移限制。因此，韩国人使用 Naver 地图和 KakaoMap。

但这给 AI Agent 带来了问题。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	查询两个站点之间的路线：线路、换乘站、乘车站台、站数、预计耗时和票价。可识别英语、韩语、日语和中文站名及地标（“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을 따릅니다.