subway-congestion-mcp

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.

Category
访问服务器

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

  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: kimjinjuind@gmail.com

Made with ❤️ for Seoul Subway Commuters

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选