MCP Servers

subway-congestion-mcp

Provides real-time and predicted congestion data, route optimization, and train arrival information for Seoul subway lines 1-8, helping users choose the best travel times.

README

🚇 지하철 혼잡도 알리미 MCP 서버

서울 지하철 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

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

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

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

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

회원가입 (무료)
상단 메뉴 "인증키 신청" 클릭
"활용 신청" 버튼 클릭
인증키 복사 → .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에 연결되지 않아요

확인 사항:

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

디버깅:

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

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

Q2. API 호출이 실패해요

확인 사항:

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

디버깅:

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

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

확인 사항:

CSV 데이터를 다운로드했는가?
```
python scripts/download_data.py
```
data/congestion/ 폴더에 파일이 있는가?
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 (계획)

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

🤝 기여하기

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

📝 라이센스

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

💬 연락처

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

GitHub Issues
Email: kimjinjuind@gmail.com

Made with ❤️ for Seoul Subway Commuters

Recommended Servers

playwright-mcp

A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.

Official

Featured

TypeScript

Magic Component Platform (MCP)

An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.

Audiense Insights MCP Server

Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.

VeyraX MCP

Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.

Official

Featured

Local

graphlit-mcp-server

The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.

Official

Featured

TypeScript

Kagi MCP Server

An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.

Official

Featured

Python

E2B

Using MCP to run code via e2b.

Official

Featured

Neon Database

MCP server for interacting with Neon Management API and databases

Official

Featured

Exa Search

A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.

Official

Featured

Qdrant Server

This repository is an example of how to create a MCP server for Qdrant, a vector search engine.

Official

Featured

subway-congestion-mcp

README

🚇 지하철 혼잡도 알리미 MCP 서버

📋 목차

✨ 주요 기능

1. 🔍 경로 검색

2. 📊 역 혼잡도 조회

3. ⏰ 도착 시간 계산

4. 🚆 열차 도착 정보

5. 🔔 지하철 이슈 검색

🎯 왜 이 프로젝트인가?

기존 앱의 한계

우리의 차별점

🚀 시작하기

필수 요구사항

설치 방법

1단계: 저장소 복제

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

3단계: 의존성 설치

4단계: 환경 설정

5단계: 데이터 다운로드

6단계: 테스트

7단계: 실행

API 키 발급

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

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

설정

.env 파일 예시

Claude Desktop 설정

💬 사용 방법

예제 1: 경로 검색

📁 폴더 구조

🛠 기술 스택

핵심 기술

주요 라이브러리

👨‍💻 개발 가이드

개발 서버 실행

테스트

코드 품질

로그 확인

🐛 문제 해결

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

Q2. API 호출이 실패해요

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

📊 성능 최적화

캐싱 전략

에러 핸들링

🔒 보안

📈 로드맵

v1.0 (현재) - MVP

v1.1 (예정)

v2.0 (계획)

🤝 기여하기

📝 라이센스

💬 연락처

Recommended Servers

`.env` 파일 예시