Skip to main content
Glama

korea-transit-mcp

CI TypeScript Node MCP License: MIT

공공데이터포털(data.go.kr)의 전국 버스 Open API를 AI 에이전트가 쓸 수 있게 만든 MCP(Model Context Protocol) 서버입니다. Claude Code, Claude Desktop, Cursor 같은 MCP 클라이언트에서 "시청역에서 106번 언제 와?" 같은 질문에 실시간 데이터로 답할 수 있습니다.

🌐 소개 페이지: 98woonho.github.io/projects/korea-transit-mcp (길 건너편 정류장 구분, 1회 환승, 운행관리 리포트 데모)

작동 방식

사용자가 질문하면 LLM(MCP 클라이언트)이 필요한 도구를 스스로 골라 순서대로 호출합니다. 서버는 공공 API를 호출해 정규화된 결과만 돌려주고, LLM을 직접 호출하지 않습니다.

sequenceDiagram
    actor U as 사용자
    participant C as MCP 클라이언트<br/>(Claude Code 등)
    participant S as korea-transit-mcp
    participant K as 캐시
    participant A as 공공데이터포털<br/>TAGO API

    U->>C: "시청역에서 비래동 가는 106번 언제 와?"
    C->>S: search_bus_stops(25, "시청역")
    S->>K: 조회
    K-->>S: miss
    S->>A: getSttnNoList
    A-->>S: 시청역 2곳 (길 건너편)
    S-->>C: 관련도 순 정렬된 정류소
    C->>S: get_routes_at_stop(시청역 #32410)
    S->>A: 경유 노선 + 노선별 경유 정류소
    S-->>C: 106번 → 비래동종점 방면 ✓
    C->>S: get_bus_arrivals(#32410, 106번)
    S->>A: 도착 예정 정보 (30초 캐시)
    S-->>C: 4분 후, 3정류장 전
    C-->>U: "시청역(32410)에서 타세요. 약 4분 후 도착"

Related MCP server: korail-mcp

제공 도구 (Tools)

국토교통부 TAGO 버스 API 4종(정류소·도착·노선·위치)을 감싼 조회 도구 9개와, 여러 API를 조합해 계산하는 분석 도구 3개입니다. 서울은 TAGO에 포함되지 않습니다.

분류

Tool

설명

정류소

list_cities

지원 도시와 도시 코드 조회 (전국 138개)

search_bus_stops

정류소명/번호 검색, 관련도 순 정렬

find_nearby_stops

좌표 주변 정류소, 가까운 순 + 거리(m)

get_routes_at_stop

정류소 경유 노선 + 다음 정류소·방면 (같은 이름의 길 건너편 정류소 구분)

도착

get_bus_arrivals

실시간 도착 예정 (분, 남은 정류장 수, 곧 도착)

노선

search_routes

노선 번호 검색, 첫차·막차

get_route_info

기점·종점, 배차간격 (평일/토/일)

get_route_stops

노선 경유 정류소 순서와 방향

위치

get_bus_locations

운행 중인 버스의 현재 정류소와 향하는 종점

분석

find_direct_routes

출발·도착 사이 직통 노선. 같은 이름 후보를 모두 받아 어느 쪽에서 타야 하는지까지 판별

find_transfer_routes

직통이 없을 때 1회 환승 경로. 두 노선의 경유 순서·방향을 대조해 실제로 이어지는 경로만, 같은 정류소 또는 걸어서(기본 200m 이내) 갈아타기

analyze_headway

운행 중인 버스의 앞뒤 차 간격: 정류장 수, 균등 배치 대비 비율, 추정 분

분석 도구는 LLM이 여러 번 호출해 직접 맞춰 볼 일을 서버에서 한 번에 결정적으로 계산합니다. 결과가 정확하고 테스트할 수 있으며, 클라이언트 토큰도 아낍니다. 몰림·공백 같은 판단 기준은 도구가 아니라 Skill이 정합니다.

예시: 이름이 같은 정류소 구분

"시청역"으로 검색하면 길 건너편 정류소 두 곳이 나옵니다. 공공 API의 "정류소 경유 노선"에는 방향 정보가 없지만, 이 서버는 노선별 경유 정류소 순서와 방향 코드(updowncd)를 합쳐서 방면을 계산합니다.

시청역(32410)  617번: 다음 목련아파트 / 비래동종점 방면
시청역(32390)  617번: 다음 시청.교육청 / 가장제일장로교회 방면

품질 검증

한 줄 요약: 같은 도구를 주고 Skill만 넣고 뺐더니 검사 통과율이 **70% → 100%**로 올랐습니다. 차이가 가장 큰 곳은 운행 리포트의 판정이었습니다(2/7 → 7/7).

Skill은 Claude에게 "이런 질문에는 이 순서로 도구를 쓰고, 이 기준으로 판단하라"고 알려 주는 지침서입니다. 이 저장소에는 이동 안내와 운행 리포트 두 개가 있습니다.

세 가지 방법으로 확인합니다

방법

확인하는 것

실행

비용

자동 테스트

계산이 맞는지 (간격 비율, 환승 경로가 실제로 이어지는지, 응답 정리 등)

npm test, push할 때마다 GitHub에서 자동 실행

무료

실제 API 점검

12개 도구가 공공데이터포털 실데이터로 동작하는지

npm run smoke

무료

Skill 평가

Claude가 Skill대로 도구를 쓰고 답하는지

npm run eval

1회 약 $1

Skill 평가는 시험처럼 진행합니다

  1. 문제: 실제 사용자처럼 질문합니다. 예: "대전 목원대학교에서 신탄진역까지 버스로 어떻게 가?" (문제 6개, plugin/evals/)

  2. 답안: Claude(Opus 5.5)가 실제 도구로 실시간 데이터를 조회해 답합니다.

  3. 채점: 문제마다 정해 둔 확인 항목을 하나씩 채점합니다. 채점 방법은 두 가지입니다.

채점 방법

이런 항목에 씁니다

누가

규칙 채점

"환승 탐색 도구를 목원대·신탄진역 정류장으로 불렀는가", "직통 탐색을 먼저 했는가"처럼 기록만 보면 답이 정해지는 항목

프로그램. 매번 같은 결과

AI 채점

"직통 노선이 없다고 분명히 말했는가"처럼 문장을 읽고 판단해야 하는 항목

Claude Haiku가 3번 판단해 다수결

두 가지를 나눈 이유가 있습니다. 평가 도구는 AI 채점관에게 실행 기록이 길면 앞부분과 뒷부분만 보여 줍니다(앞뒤 12개 메시지). 가운데 있던 도구 호출은 AI 채점관이 볼 수 없어서, "어떤 도구를 불렀나"는 규칙 채점으로, "어떻게 답했나"는 항상 보이는 최종 답변을 AI가 채점하도록 나눴습니다.

결과 1: Skill이 있을 때와 없을 때 (2026-11-17, v0.3.2)

문제

확인 항목

Skill 있음

Skill 없음

길 건너편 정류장 구분 (시청역 → 목련아파트)

맞는 쪽 정류장(32410) 안내, 반대편 주의, 없는 노선 지어내지 않기 등

5/5

5/5

직통 노선 없음 (목원대 → 신탄진역)

직통 없음 안내, 확인 안 된 환승 경로 지어내지 않기 등

4/4

4/4

도시를 말하지 않음

도시를 묻거나, 가정한 도시를 밝히기

1/1

1/1

106번 운행 리포트

판정 기준대로 몰림·공백 판정, 종점·기점 구간 제외, 노선 등급

7/7

2/7

사용자 기준 우선 ("2배부터 공백")

사용자가 말한 기준 적용

2/2

2/2

승객의 도착 문의

운행 리포트로 착각하지 않기

2/2

2/2

합계

23/23 (100%)

16/23 (70%)

알게 된 것

  • Skill의 효과는 "판단"에서 나타났습니다. Skill이 없으면 분석 도구는 똑같이 불렀지만, 판정에서 빼야 할 기점 구간을 "심한 공백"으로 판정하고, 정상 범위(1.48배)도 공백으로 올리고, 노선 등급을 내지 않았습니다.

  • 길 건너편 정류장 구분은 Skill이 없어도 맞혔습니다. 정류장 후보를 모두 받아 서버가 판별하도록 도구를 설계했기 때문입니다. "계산은 도구에, 판단 기준은 Skill에"라는 원칙이 결과로 확인됐습니다.

  • Skill이 지나치게 조심스러운 곳도 찾았습니다. 직통 노선이 없을 때 Skill은 "환승은 확인할 수 없다"며 지도 앱을 권했습니다. 그런데 Skill 없는 Claude는 노선별 정류장 목록을 직접 대조해 맞는 환승 경로를 찾아냈습니다. 그래서 이 계산을 서버 도구(find_transfer_routes)로 만들었습니다. → 결과 2

결과 2: 환승 도구 추가 후 (2026-11-17, v0.4.0)

"목원대 → 신탄진역" 문제를 다시 풀게 했습니다.

확인 항목

채점

결과

직통 노선부터 찾았다 (목원대·신탄진역 정류장으로)

규칙

✅

직통 노선이 없다고 안내했다

AI

✅

그다음 환승 경로를 찾았다 (직통 → 환승 순서)

규칙

✅

환승 탐색에 같은 정류장 후보를 넘겼다

규칙

✅

두 버스 번호, 탈 곳, 갈아탈 정류장 번호까지 안내했다

AI

✅

5/5 (비용 $0.20). 실제 답변: "목원대학교(33230)에서 106번 → 29정류장 뒤 복합터미널(12010)에서 같은 정류장의 급행 2번으로 환승 → 10정류장 뒤 신탄진역". 같은 시각 실제 API 점검 결과와 일치했습니다.

AI 채점을 사람이 다시 확인했습니다. 결과 1의 46개 판정(23개 항목 × 2)을 실행 기록과 하나씩 대조했고, 운행 리포트는 도구 결과로 등급을 직접 다시 계산했습니다. 1개가 틀렸습니다. Skill 없는 Claude의 환승 경로를 "확인 안 된 경로"로 감점했는데, 실제로는 도구로 확인된 맞는 경로였습니다. 원인은 AI가 아니라 제가 쓴 채점 기준 문장에 "어떤 도구도 환승을 확인하지 않았으므로"라는 틀린 전제가 있었던 것입니다. 이 판정을 고쳐서 Skill 없음 결과가 15/23에서 16/23이 됐습니다.

한계

  • 문제당 1번만 풀게 해서 표본이 작습니다.

  • 실시간 데이터라 두 조건이 본 상황이 조금 다릅니다(약 6분 차이). Skill 있을 때는 106번 간격이 마침 모두 정상이어서 "몰림·공백을 기준대로 판정하는가"는 제대로 시험되지 않았습니다.

  • "판정 기준 파일을 읽었다", "리포트 형식" 같은 항목은 Skill이 정한 것이라 Skill이 없으면 틀리는 게 당연합니다.

  • 결과 1의 실행 12개 중 8개는 AI 채점관이 기록 가운데를 보지 못했습니다(위의 "앞뒤만 보여 주는" 문제). 저장된 기록도 똑같이 잘려 있어서, 그 구간의 도구 호출은 사람의 재확인으로도 볼 수 없었습니다. 그 뒤 모든 문제의 "○○ 도구를 불렀다" 항목을 규칙 채점으로 바꾸고, 답변 내용 항목은 최종 답변만 보도록 바꿨습니다. 결과 1은 바꾸기 전 방식으로 채점한 것입니다.

다시 평가하기

npm run eval                            # 전체 6문제, 1번씩, 비용 상한 $3
npm run eval -- --case no-direct-route  # 한 문제만
npm run eval -- --model sonnet          # 답하는 모델 바꾸기 (기본: 지금 Claude Code 설정 모델)

Claude Code CLI(claude)가 필요합니다. 저장소 안에서 실행하면 플러그인이 이 저장소의 빌드를 쓰므로 릴리스 전 변경을 평가할 수 있고, 인증키는 .env에서 읽습니다.

설계 원칙: LLM 비용 0원

  • 서버는 LLM을 호출하지 않습니다. 추론은 사용자의 MCP 클라이언트가 하고, 서버는 결정적인 도구만 제공합니다.

  • 잘 바뀌지 않는 데이터(도시 코드, 정류소)는 TTL 캐시로 공공 API 일일 호출 한도를 아낍니다.

  • 테스트는 가짜 fetch와 인메모리 MCP 트랜스포트로 돌아가서 CI에서 네트워크와 LLM 비용이 들지 않습니다.

시작하기

1. 인증키 발급

  1. 공공데이터포털 회원가입

  2. "국토교통부_(TAGO)_버스정류소정보" 등 필요한 API에 활용신청 (대부분 자동승인)

  3. 마이페이지 > 개인 API 인증키에서 Decoding 키를 복사

2-A. Claude Code 플러그인으로 설치 (추천: MCP 서버 + Skill 한 번에)

/plugin install korea-transit --marketplace 98Woonho/korea-transit-mcp

플러그인을 켤 때 인증키 입력 창이 뜹니다. 키는 OS 보안 저장소에 보관되고 설정 파일에는 남지 않습니다. 설치하면 MCP 도구 12개와 함께 아래 Skill이 들어옵니다.

Skill

이렇게 물어보세요

하는 일

korea-transit:bus-trip

"대전 시청역에서 목련아파트까지 버스 뭐 타?"

길 건너편 정류장까지 구분해 탈 곳, 노선, 실시간 도착을 안내. 직통이 없으면 검증된 1회 환승 경로

korea-transit:route-ops-report

"대전 106번 운행 상태 분석해줘"

배차간격 대비 몰림·공백 구간을 판정한 운행관리 리포트

2-B. MCP 서버만 연결 (다른 클라이언트, npx로 실행)

Claude Code

claude mcp add korea-transit -e DATA_GO_KR_SERVICE_KEY=발급받은_Decoding_키 -- npx -y korea-transit-mcp

Claude Desktop / Cursor 등 설정 파일의 mcpServers에 추가:

{
  "mcpServers": {
    "korea-transit": {
      "command": "npx",
      "args": ["-y", "korea-transit-mcp"],
      "env": { "DATA_GO_KR_SERVICE_KEY": "발급받은_Decoding_키" }
    }
  }
}

Node.js 20.12 이상이 필요합니다.

개발

npm install
cp .env.example .env   # DATA_GO_KR_SERVICE_KEY 입력
npm test               # 네트워크·LLM 없이 도는 테스트
npm run smoke          # 실제 API로 전체 도구 점검
npm run inspect        # MCP Inspector로 도구 직접 실행

이 저장소를 Claude Code로 열면 .mcp.json으로 로컬 빌드(dist/)가 자동 연결되고, 키는 서버가 .env에서 직접 읽습니다.

릴리스는 npm version 후 태그를 push하면 GitHub Actions가 npm 배포(Trusted Publishing)와 MCP 레지스트리 갱신까지 자동으로 합니다. 자세한 내용은 docs/RELEASING.md를 참고하세요.

구조

src/
  index.ts              # stdio 엔트리포인트
  server.ts             # 의존성 조립
  cache.ts              # TTL 캐시 (원격 배포 시 KV로 교체 가능)
  datagokr/client.ts    # data.go.kr 공통 클라이언트 (응답 정규화, 오류 처리)
  tago/                 # TAGO API 어댑터: 원본 필드 → 정규화된 도메인 객체
    stations.ts         #   정류소 (검색, 주변, 경유 노선)
    arrivals.ts         #   도착 정보
    routes.ts           #   노선, 경유 정류소, 버스 위치, 방향 계산
  analysis/             # 순수 계산 로직 (직통·환승 경로, 운행 간격 분석) — API 호출 없음
  tools/                # MCP 도구 정의 (설명, 입력 스키마, 응답 가공)
plugin/                 # Claude Code 플러그인 (마켓플레이스: .claude-plugin/marketplace.json)
  .claude-plugin/plugin.json  # 매니페스트, 인증키 입력(userConfig)
  .mcp.json             #   npm 패키지를 실행하는 MCP 설정
  bin/launch.mjs        #   플러그인 버전과 같은 npm 버전을 실행 (Windows 호환)
  skills/               #   bus-trip, route-ops-report
scripts/smoke.ts        # 실제 API로 전체 도구 점검
test/                   # 가짜 fetch + 인메모리 MCP 클라이언트 테스트
docs/public-apis.md     # 사용 가능한 공공 API 정리
showcase/               # 포트폴리오 사이트가 빌드 시 읽는 소개 자료
  showcase.json         #   소개, 링크, 설치 안내, 도구 분류
  demos/*.json          #   데모 시나리오: 실제 실행 기록을 요약한 녹화본 (사이트에서 애니메이션으로 재생)

캐시 정책 (공공 API 일일 한도 보호)

데이터

TTL

도시 코드

24시간

정류소, 노선, 경유 정류소/노선

6시간

도착 정보

30초

버스 위치

15초

License

MIT

Available Tools

12 tools
analyze_headway노선 운행 간격 분석A

노선에서 운행 중인 버스들의 앞뒤 차 간격을 계산합니다. 각 간격의 정류장 수(gapStops), 균등 배치 대비 비율(ratio, 1이 균등), 추정 시간 간격(estMin, 분)을 돌려줍니다. ratio가 작으면 앞차와 붙어 있는 것(몰림)이고, 크면 간격이 벌어진 것(공백)입니다. 마지막 간격(crossesOrigin)은 노선 끝에서 기점을 지나 첫 차까지의 순환 간격이고, 위치를 모르는 차량은 unlocatedBuses로 따로 돌려줍니다. 판단 기준은 이 도구가 정하지 않으니, 결과의 notes에 적힌 가정과 한계를 함께 안내하세요.

Inputs: routeId (required), cityCode (required).

find_direct_routes직통 노선 찾기A

출발 정류소에서 도착 정류소까지 갈아타지 않고 가는 버스 노선을 찾습니다(이동 정류장 수가 적은 순). 이름이 같은 출발·도착 후보를 모두 넘기면, 어느 쪽 정류소에서 타고 내려야 하는지(fromNodeId/toNodeId)까지 판별합니다. 결과가 비어 있으면 직통 노선이 없는 것이니 find_transfer_routes로 환승 경로를 찾으세요. viaTurnaround가 true면 종점에서 회차해 가는 경로라 안내 시 언급하세요.

Inputs: cityCode (required), toNodeIds (required), fromNodeIds (required).

find_nearby_stops주변 정류소 찾기A

위도·경도 주변의 버스 정류소를 가까운 순으로 찾습니다(distanceM: 미터). 도시 코드가 필요 없고, 결과에 cityCode가 포함됩니다. 같은 정류소가 인접 도시 시스템에 중복 등록되어 cityCode만 다르게 두 번 나올 수 있습니다.

Inputs: lat (required), lng (required), limit.

find_transfer_routes1회 환승 경로 찾기A

직통 노선이 없을 때, 한 번 갈아타서 가는 경로를 찾습니다(두 구간 이동 정류장 수 합이 적은 순). 출발 정류소를 지나는 노선과 도착 정류소를 지나는 노선의 경유 순서·방향을 대조해서, 실제로 이어지는 경로만 돌려줍니다. 같은 정류소에서 갈아타면 sameStop=true, 근처 정류소로 걸어가 갈아타면 walkM(직선거리, m)을 줍니다. 먼저 find_direct_routes를 쓰고, 결과가 비었을 때 같은 후보 목록으로 호출하세요. 정류장 수 기준이라 실제 소요 시간과는 다를 수 있습니다.

Inputs: cityCode (required), toNodeIds (required), fromNodeIds (required), limit, +1 more.

get_bus_arrivals실시간 버스 도착 정보A

정류소에 도착 예정인 버스를 도착이 빠른 순으로 조회합니다. nodeId는 search_bus_stops 결과에서 얻습니다. routeId를 주면 해당 노선만 조회합니다. arrivalMin은 남은 시간(분, 반올림), stopsAway는 몇 정류장 전인지입니다. arrivingSoon이 true이면 1분 이내이므로 분 대신 '곧 도착'으로 안내하세요. 결과가 비어 있으면 현재 운행 중인 도착 예정 버스가 없는 것입니다.

Inputs: nodeId (required), cityCode (required), routeId.

get_bus_locations실시간 버스 위치A

노선에서 현재 운행 중인 버스들의 위치(차량번호, 현재 정류소, 노선 내 순번)를 조회합니다. towards는 그 버스가 향하는 종점 방향입니다. 결과가 비어 있으면 운행 중인 버스가 없는 것입니다.

Inputs: routeId (required), cityCode (required).

get_route_info버스 노선 상세A

노선의 기점·종점, 첫차·막차 시각, 배차간격(분: 평일/토요일/일요일·공휴일)을 조회합니다.

Inputs: routeId (required), cityCode (required).

get_routes_at_stop정류소 경유 노선A

정류소를 지나는 버스 노선 목록입니다. 각 노선에 이 정류소의 다음 정류소(nextStop)와 향하는 종점(towards)을 붙여 줍니다. 같은 이름의 정류소가 여러 개일 때 어느 쪽 방면인지 구분하는 데 사용하세요. 노선이 20개를 넘으면 방향 정보는 생략됩니다.

Inputs: nodeId (required), cityCode (required).

get_route_stops노선 경유 정류소B

노선이 지나는 정류소를 순서대로 조회합니다. direction이 0이면 기점→종점, 1이면 종점→기점 방향 구간입니다. 정류소가 수십~수백 개일 수 있으니 필요할 때만 호출하세요.

Inputs: routeId (required), cityCode (required).

list_cities도시 코드 조회A

국토교통부(TAGO) 버스 API가 지원하는 도시와 도시 코드(cityCode)를 조회합니다. 다른 버스 도구를 호출하기 전에 cityCode를 알아내는 데 사용하세요. query를 주면 도시명에 해당 문자열이 포함된 것만 돌려줍니다. 서울특별시는 TAGO에서 지원하지 않습니다.

Inputs: query.

search_bus_stops버스 정류소 검색A

도시 코드와 정류소명(또는 정류소 번호)으로 버스 정류소를 검색합니다. 결과는 이름이 검색어와 정확히 일치 → 앞부분 일치 → 포함 순으로 정렬됩니다. 같은 이름의 정류소가 여러 개면 도로 반대편 등 방향이 다른 정류소입니다(get_routes_at_stop으로 방향 확인). 하나의 도시 코드에 인접 시·군이 함께 묶여 있을 수 있습니다. 결과의 nodeId는 도착 정보 조회 등 다른 도구에서 사용됩니다.

Inputs: cityCode (required), name, limit, stopNo.

search_routes버스 노선 검색A

노선 번호로 버스 노선을 검색합니다. 기점·종점과 첫차·막차 시각(HH:MM)을 함께 돌려줍니다. 결과의 routeId는 다른 노선 도구에서 사용됩니다. 같은 번호라도 지역·유형별로 여러 노선이 나올 수 있습니다.

Inputs: routeNo (required), cityCode (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools have sharply distinct roles, and the descriptions explicitly sequence dependent tools (list_cities → search_bus_stops → get_bus_arrivals, and find_direct_routes → find_transfer_routes as a fallback). The only real overlap is search_routes vs get_route_info, which both return origin/destination and first/last times, and search_bus_stops vs find_nearby_stops, though those differ by name vs coordinates.

    Naming Consistency5/5

    Every tool follows a consistent snake_case verb_noun pattern (list_cities, get_bus_locations, find_direct_routes, search_bus_stops, analyze_headway). Verb choice is also semantically meaningful: list/search for discovery, get for direct lookup, find for route computation.

    Tool Count5/5

    12 tools is well within the ideal 3-15 range, and each one earns its place by covering a distinct step in a bus-trip workflow (city → stop → route → arrival → routing → headway). No obvious filler or near-duplicate tools.

    Completeness4/5

    The bus domain is covered end to end: discovery by name and by coordinates, route lookup, stop sequences, real-time arrivals and vehicle positions, single-transfer routing, and headway analysis. Minor gaps remain, such as no fare/service-alert information and no subway or intercity coverage despite the 'korea-transit' server name (Seoul is also explicitly unsupported).

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers