# korea-transit-mcp-server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

> [English](./README.md)

한국 대중교통 MCP 서버 — 경로 탐색, 실시간 버스/지하철 도착 정보, 혼잡도 조회

**ODsay LAB** (전국 대중교통 경로 탐색) + **서울 공공데이터** (실시간 도착/혼잡도)를 조합하여, AI 어시스턴트가 *"강남역에서 판교까지 지금 뭐 타고 가?"* 같은 질문에 직접 답할 수 있습니다.

## 제공 도구

| 도구 | 설명 |
|------|------|
| `transit_route` | 대중교통 경로 검색 (출발지 → 도착지) |
| `station_search` | 정류장/역 검색 |
| `line_info` | 노선 정보 조회 (경유 정류장, 운행 정보) |
| `nearby_stations` | 주변 정류장/역 검색 (좌표 기반) |
| `bus_arrival` | 실시간 버스 도착 정보 |
| `bus_location` | 실시간 버스 위치 추적 |
| `subway_arrival` | 실시간 지하철 도착 정보 |
| `subway_congestion` | 지하철 혼잡도 조회 (시간대별) |
| `first_last_train` | 첫차/막차 시간 조회 |

## 사전 준비

3개 API 키가 필요합니다 (모두 무료):

| API | 발급처 | 용도 |
|-----|--------|------|
| **ODsay LAB** | [lab.odsay.com](https://lab.odsay.com/) | 경로 탐색, 정류장/역 검색 |
| **서울시 버스 API** | [data.go.kr](https://www.data.go.kr/) | 실시간 버스 도착/위치 |
| **서울 열린데이터** | [data.seoul.go.kr](https://data.seoul.go.kr/) | 실시간 지하철 도착/혼잡도 |

### API 키 발급 방법

**1. ODsay LAB** (즉시 발급)
1. [lab.odsay.com](https://lab.odsay.com/) 가입 → 로그인
2. 마이페이지 → 서비스 등록 (서비스명: `korea-transit-mcp-server`, 도메인: `localhost`)
3. API Key 복사

**2. 서울시 버스 API** (즉시~1시간)
1. [data.go.kr](https://www.data.go.kr/) 가입 → 로그인
2. 검색: "서울특별시 정류소정보조회 서비스" → 활용신청
3. 마이페이지 → Open API → 인증키 복사

**3. 서울 열린데이터** (즉시)
1. [data.seoul.go.kr](https://data.seoul.go.kr/) 가입 → 로그인
2. 검색: "서울시 지하철 실시간 도착정보" → 인증키 신청
3. 마이페이지 → 인증키 복사

## 설치 및 설정

### Claude Code / Claude Desktop

#### 옵션 1: PyPI 패키지 사용

MCP 설정에 추가:

```json
{
  "mcpServers": {
    "korea-transit": {
      "command": "uvx",
      "args": ["korea-transit-mcp-server"],
      "env": {
        "ODSAY_API_KEY": "발급받은_키",
        "SEOUL_BUS_API_KEY": "발급받은_키",
        "SEOUL_SUBWAY_API_KEY": "발급받은_키"
      }
    }
  }
}
```

#### 옵션 2: 로컬 저장소에서 실행 (개발용)

저장소를 클론하고 직접 실행하는 경우:

**1. 저장소 클론 및 설치**
```bash
git clone https://github.com/SimDaSong/korea-transit-mcp-server.git
cd korea-transit-mcp-server
uv pip install -e .
```

**2. MCP 설정 파일 작성**

프로젝트의 `.mcp.json.example`을 복사하여 `.mcp.json` 생성 후 API 키 입력:

```json
{
  "mcpServers": {
    "korea-transit": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "korea-transit-mcp-server"],
      "env": {
        "ODSAY_API_KEY": "발급받은_키",
        "SEOUL_BUS_API_KEY": "발급받은_키",
        "SEOUL_SUBWAY_API_KEY": "발급받은_키"
      }
    }
  }
}
```

### 로컬 개발

```bash
git clone https://github.com/SimDaSong/korea-transit-mcp-server.git
cd korea-transit-mcp-server
uv sync --group dev

# 환경변수 설정
export ODSAY_API_KEY="발급받은_키"
export SEOUL_BUS_API_KEY="발급받은_키"
export SEOUL_SUBWAY_API_KEY="발급받은_키"

# 서버 실행
uv run -m korea_transit_mcp_server

# 테스트
uv run pytest -v
```

## 사용 예시

### 경로 검색
> "강남역에서 판교역까지 대중교통 경로 알려줘"

→ `transit_route(start="강남역", end="판교역")` 호출

### 실시간 버스 도착
> "22009번 정류소에 오는 버스 알려줘"

→ `bus_arrival(ars_id="22009")` 호출

### 지하철 도착
> "강남역 지하철 언제 와?"

→ `subway_arrival(station_name="강남")` 호출

### 혼잡도
> "2호선 강남역 혼잡도 어때?"

→ `subway_congestion(line_num="2", station_name="강남")` 호출

### 주변 역 찾기
> "내 위치 주변에 지하철역 있어?" (좌표: 127.027, 37.498)

→ `nearby_stations(longitude=127.027, latitude=37.498)` 호출

## API 제한

- **ODsay**: 무료 1,000콜/일 (호출 수 자동 추적, 초과 시 경고)
- **서울 버스/지하철**: 공공데이터, 일반적으로 넉넉한 한도

## 캐싱 전략

| 데이터 유형 | TTL | 이유 |
|-------------|-----|------|
| 경로 검색 | 10분 | 자주 변하지 않음 |
| 정류장/역 정보 | 1일 | 거의 고정 데이터 |
| 혼잡도 통계 | 30분 | 분기별 통계 데이터 |
| 실시간 도착 | 캐시 안 함 | 항상 최신이어야 함 |

## 기술 스택

- Python 3.11+ / [FastMCP](https://github.com/jlowin/fastmcp) (공식 MCP SDK)
- [httpx](https://www.python-httpx.org/) (비동기 HTTP 클라이언트)
- [uv](https://docs.astral.sh/uv/) (패키지 관리)

## 라이선스

MIT
