subway-mcp — 수원역 지하철 실시간 도착정보 MCP 서버

수원역의 1호선 / 수인분당선 실시간 도착정보를, Claude 같은 MCP 클라이언트가 조회할 수 있게 해주는 로컬 stdio MCP 서버입니다. 첫 MCP 서버 학습용 프로젝트.

구조

파일	역할
server.py	FastMCP 서버 + @mcp.tool 정의만 (얇게 유지)
subway_api.py	도착정보 API 호출/파싱 (도메인 로직 격리)
.env	SUBWAY_SERVICE_KEY=... (git 커밋 금지)
.env.example	키 이름만 적어둔 템플릿

개발 환경 준비 (uv)

cd C:\Users\admin\HJ\subway-mcp
uv sync                       # 의존성 설치 + 가상환경 생성

실행 / 디버깅 (MCP Inspector)

uv run fastmcp dev server.py  # 브라우저로 Inspector 가 열리고 툴을 직접 호출 가능

진행 상태 (마일스톤)

• [x] M1 — 빈 서버 + hello 더미 툴
• [x] M2 — 데이터 소스 검증 → TOPIS 확정 (역명은 "수원"으로 조회)
• [x] M3 — get_subway_arrivals (전체 도착정보)
• [x] M4 — get_line_arrivals (호선/방향 필터)
• [ ] M5 — Claude Code / Desktop 연결
• [x] M6 — 에러 처리·한국어 포맷 (역명 오류/노선 오류/타임아웃/키 없음)

Claude 연결

Claude Code (모든 프로젝트에서 사용):

claude mcp add --scope user subway-info -- uv run --directory C:\Users\admin\HJ\subway-mcp python server.py

Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json 의 mcpServers 에 등록 후 앱 재시작.

{
  "mcpServers": {
    "subway-info": {
      "command": "C:\\Users\\admin\\.local\\bin\\uv.exe",
      "args": ["run", "--directory", "C:\\Users\\admin\\HJ\\subway-mcp", "python", "server.py"]
    }
  }
}

키 발급

.env.example 을 .env 로 복사한 뒤 발급받은 서비스키를 넣으세요.

• TOPIS: https://data.seoul.go.kr — "지하철 실시간 도착정보" 인증키 신청