Subway Congestion

서울 지하철 1~8호선의 혼잡도 정보를 제공하는 Model Context Protocol (MCP) 서버

출퇴근 시간대에 지하철이 얼마나 혼잡한지 미리 알고, 가장 쾌적한 시간에 이동할 수 있도록 도와주는 똑똑한 비서입니다.

---

📋 목차

• 주요 기능
• 왜 이 프로젝트인가?
• 시작하기
• 사용 방법
• 폴더 구조
• 개발 가이드
• 문제 해결

---

✨ 주요 기능

1. 🔍 경로 검색

"강남역에서 역삼역 가려는데"
→ 최적 경로 + 혼잡도 정보 + 대안 경로 2개 제시

2. 📊 역 혼잡도 조회

"강남역 지금 혼잡해?"
→ 실시간 혼잡도 + 다음 열차 도착 시간

3. ⏰ 도착 시간 계산

"강남에서 역삼까지 9시까지 도착해야 해"
→ 필요한 출발 시간 + 그 시간대 혼잡도

4. 🚆 열차 도착 정보

"강남역 열차 언제 와?"
→ 다음 3개 열차 도착 시간 + 각 혼잡도

5. 🔔 지하철 이슈 검색

"2호선 지금 지연돼?"
→ 최신 운행 이슈, 고장, 시위 정보

---

🎯 왜 이 프로젝트인가?

기존 앱의 한계

• 네이버/카카오맵: 혼잡도 정보 없음
• 서울교통공사 앱: 실시간 정보만 제공, 예측 불가

우리의 차별점

✅ 통계 기반 예측: 과거 데이터로 시간대별 혼잡도 예측
✅ 의사결정 지원: "지금 vs 30분 후" 비교 제공
✅ 대화형 인터페이스: Claude와 자연어로 소통
✅ 대안 제시: 단순 정보 → 최적 선택 추천

---

🚀 시작하기

필수 요구사항

• Python 3.10 이상
• pip 또는 uv (권장)
• Claude Desktop (MCP 클라이언트)
• API 키 2개 (무료, 필수):
  • ODsay API Key
  • 서울시 Open API Key
  • (선택) Kakao REST API Key

---

설치 방법

1단계: 저장소 복제

git clone https://github.com/yourusername/subway-congestion-mcp.git
cd subway-congestion-mcp

2단계: 가상환경 생성 (권장)

# uv 사용 (권장 - 빠름)
uv venv
source .venv/bin/activate  # Mac/Linux
# 또는
.venv\Scripts\activate  # Windows

# 또는 일반 venv
python -m venv .venv
source .venv/bin/activate

3단계: 의존성 설치

# uv 사용
uv pip install -e .

# 또는 pip 사용
pip install -e .

4단계: 환경 설정

cp .env.example .env
# .env 파일을 열어서 API 키 입력

5단계: 데이터 다운로드

python scripts/download_data.py

6단계: 테스트

pytest

7단계: 실행

# 가상환경 활성화 상태에서 실행
python -m subway_congestion_mcp

---

API 키 발급

1. ODsay API (대중교통 경로 검색)

발급 사이트: https://lab.odsay.com

1. 회원가입 (무료)
2. "API 사용 신청" 클릭
3. 앱 정보 입력:
   • 앱 이름: 지하철 혼잡도 알리미
   • 사용 목적: 개인 프로젝트
   • 플랫폼: Web/Mobile
4. API 키 복사 → .env 파일의 ODSAY_API_KEY에 붙여넣기

제한: 하루 1,000건 (무료)

---

2. 서울시 Open API (실시간 도착 정보)

발급 사이트: https://data.seoul.go.kr

1. 회원가입 (무료)
2. 상단 메뉴 "인증키 신청" 클릭
3. "활용 신청" 버튼 클릭
4. 인증키 복사 → .env 파일의 SEOUL_API_KEY에 붙여넣기

제한: 하루 1,000건 (무료)

---

설정

.env 파일 예시

# ODsay API (필수)
ODSAY_API_KEY=your_odsay_api_key_here

# 서울시 Open API (필수)
SEOUL_API_KEY=your_seoul_api_key_here

# 로그 레벨 (DEBUG, INFO, WARNING, ERROR)
LOG_LEVEL=INFO

# 캐시 TTL (초)
CACHE_TTL=300

Claude Desktop 설정

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "subway-congestion": {
      "command": "uv",
      "args": [
        "--directory",
        "/절대경로/subway-congestion-mcp",
        "run",
        "subway-congestion-mcp"
      ]
    }
  }
}

또는 일반 Python 사용 시:

{
  "mcpServers": {
    "subway-congestion": {
      "command": "python",
      "args": [
        "-m",
        "subway_congestion_mcp"
      ],
      "env": {
        "PYTHONPATH": "/절대경로/subway-congestion-mcp/src"
      }
    }
  }
}

설정 후 Claude Desktop을 재시작하세요.

---

💬 사용 방법

예제 1: 경로 검색

사용자: "강남역에서 역삼역 가려는데"

Claude: 
🚇 최적 경로: 2호선 상선 직통 (1역, 2분)
 • 강남역: 혼잡도 152% (매우혼잡) ⛔
 • 역삼역: 혼잡도 148% (혼잡) 🔴

📌 대안 경로:
 1. 9호선 환승 (12분) - 혼잡도 정보 없음
 2. 146번 버스 (15분) - 혼잡도 정보 없음

💡 2호선이 가장 빠르지만 현재 매우 혼잡합니다.

---

📁 폴더 구조

subway-congestion-mcp/
├── README.md                    # 👈 지금 보고 있는 파일
├── pyproject.toml               # 프로젝트 메타데이터 및 의존성
├── .env.example                 # 환경 변수 템플릿
├── .gitignore                   # Git 제외 파일
│
├── src/
│   └── subway_congestion_mcp/   # 메인 패키지
│       ├── __init__.py
│       ├── __main__.py          # MCP 서버 진입점
│       │
│       ├── server.py            # MCP 서버 설정
│       │
│       ├── tools/               # MCP 도구 정의
│       │   ├── __init__.py
│       │   ├── search_route.py          # 경로 검색
│       │   ├── get_station_congestion.py  # 역 혼잡도 조회
│       │   ├── get_route_congestion.py    # 경로 혼잡도 + 시간 계산
│       │   ├── get_train_arrival.py       # 열차 도착 정보
│       │   └── search_issues.py           # 지하철 이슈 검색
│       │
│       ├── services/            # 비즈니스 로직
│       │   ├── __init__.py
│       │   ├── odsay_service.py     # ODsay API 호출
│       │   ├── seoul_metro_service.py # 서울시 API 호출
│       │   ├── congestion_service.py  # 혼잡도 계산 로직
│       │   └── cache_service.py       # 캐싱 레이어
│       │
│       ├── data/                # 데이터 처리
│       │   ├── __init__.py
│       │   ├── loader.py        # CSV 데이터 로더
│       │   ├── parser.py        # 데이터 파싱
│       │   └── validator.py     # 데이터 검증
│       │
│       ├── utils/               # 유틸리티
│       │   ├── __init__.py
│       │   ├── logger.py        # 로깅 설정
│       │   ├── time_utils.py    # 시간 변환
│       │   ├── error_handler.py # 에러 핸들링
│       │   └── constants.py     # 상수 정의
│       │
│       └── models/              # 데이터 모델 (Pydantic)
│           ├── __init__.py
│           ├── route.py         # 경로 관련 모델
│           ├── station.py       # 역 관련 모델
│           └── congestion.py    # 혼잡도 관련 모델
│
├── data/                        # 정적 데이터
│   ├── congestion/              # 혼잡도 CSV 파일
│   │   ├── line1.csv
│   │   ├── line2.csv
│   │   └── ...
│   └── stations.json            # 역 정보 (좌표, 노선 등)
│
├── tests/                       # 테스트 코드
│   ├── __init__.py
│   ├── test_services/           # 서비스 테스트
│   │   ├── test_odsay_service.py
│   │   └── test_congestion_service.py
│   └── test_tools/              # 도구 테스트
│       ├── test_search_route.py
│       └── test_get_station_congestion.py
│
├── scripts/                     # 유틸리티 스크립트
│   ├── download_data.py         # CSV 데이터 다운로드
│   └── validate_env.py          # 환경 변수 검증
│
└── logs/                        # 로그 파일 (gitignore)

---

🛠 기술 스택

핵심 기술

• Python 3.10+ - 런타임
• MCP SDK - Model Context Protocol
• Pydantic - 데이터 검증
• pandas - CSV 데이터 처리

주요 라이브러리

[project]
dependencies = [
    "mcp>=0.9.0",              # MCP SDK
    "pydantic>=2.0.0",         # 데이터 검증
    "pandas>=2.0.0",           # CSV 처리
    "requests>=2.31.0",        # HTTP 클라이언트
    "python-dateutil>=2.8.2",  # 날짜/시간 처리
    "python-dotenv>=1.0.0",    # 환경 변수
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",           # 테스트 프레임워크
    "pytest-asyncio>=0.21.0",  # 비동기 테스트
    "black>=23.0.0",           # 코드 포맷팅
    "ruff>=0.1.0",             # 린팅
    "mypy>=1.5.0",             # 타입 체킹
]

---

👨‍💻 개발 가이드

개발 서버 실행

# MCP Inspector로 테스트
npx @modelcontextprotocol/inspector uv --directory . run subway-congestion-mcp

# 또는 직접 실행
python -m subway_congestion_mcp

테스트

# 전체 테스트
pytest

# 특정 파일 테스트
pytest tests/test_services/test_congestion_service.py

# 커버리지 확인
pytest --cov=subway_congestion_mcp --cov-report=html

코드 품질

# 포맷팅
black src/

# 린팅
ruff check src/

# 타입 체킹
mypy src/

로그 확인

# 실시간 로그
tail -f logs/app.log

# 에러 로그만
tail -f logs/error.log

---

🐛 문제 해결

Q1. MCP 서버가 Claude Desktop에 연결되지 않아요

확인 사항:

1. claude_desktop_config.json 경로가 정확한가?
2. 절대 경로를 사용했는가?
3. 가상환경이 활성화되어 있는가?
4. Claude Desktop을 재시작했는가?

디버깅:

# 직접 실행해보기
cd /절대경로/subway-congestion-mcp
source .venv/bin/activate
python -m subway_congestion_mcp

# 로그 확인
cat ~/Library/Logs/Claude/mcp*.log

---

Q2. API 호출이 실패해요

확인 사항:

1. .env 파일에 API 키가 정확히 입력되었는가?
2. API 키가 유효한가?
3. 인터넷 연결이 정상인가?

디버깅:

# 스크립트로 API 키 테스트
python scripts/test_api_keys.py

---

Q3. 혼잡도 데이터가 없다고 나와요

확인 사항:

1. CSV 데이터를 다운로드했는가?

   python scripts/download_data.py
   

2. data/congestion/ 폴더에 파일이 있는가?
3. 1~8호선 역인가? (9호선 미지원)

---

📊 성능 최적화

캐싱 전략

• 혼잡도 데이터: 메모리 캐시 (pandas DataFrame)
• 실시간 도착 정보: 30초 TTL
• 경로 검색 결과: 10분 TTL

에러 핸들링

# Retry 데코레이터
@retry(max_attempts=3, backoff=exponential)
async def call_api():
    ...

# Fallback 전략
try:
    return await get_realtime_data()
except APIError:
    return get_statistical_data()  # 통계 데이터로 대체

---

🔒 보안

• ✅ API 키는 .env 파일에만 저장하고 .gitignore로 커밋 제외
• ✅ 키 유출 시 즉시 재발급 및 폐기
• ✅ 샘플 설정은 .env.example만 공유
• ✅ 민감한 정보는 로그에 남기지 않음
• ✅ 의존성은 pyproject.toml에서 관리

---

📈 로드맵

v1.0 (현재) - MVP

• ✅ 기본 5가지 도구 구현
• ✅ 1~8호선 지원
• ✅ 통계 기반 혼잡도

v1.1 (예정)

• ⬜ 9호선, 신분당선 지원
• ⬜ 대안 역 추천
• ⬜ 웹 인터페이스

v2.0 (계획)

• ⬜ 개인화 기능
• ⬜ 알림 설정
• ⬜ 통계 대시보드

---

🤝 기여하기

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📝 라이센스

MIT License - 자유롭게 사용하세요!

---

💬 연락처

문의사항이나 제안사항이 있으시면:

• GitHub Issues
• Email: [email protected]

---

Made with ❤️ for Seoul Subway Commuters