weather-forecast-mcp

기상청 단기예보 조회서비스(VilageFcstInfoService_2.0)를 MCP(Model Context Protocol) 서버로서 제공합니다. 초단기실황(超短時間実況), 초단기예보(超短時間予報), 단기예보(短期予報), 예보버전(予報バージョン)의 4개 오퍼레이션을 지역명 또는 격자 좌표(nx, ny)로 조회할 수 있습니다.

Dataset Registry

이 MCP는 단일 API(오퍼레이션 4종)로 구성되며, 별도 데이터셋 통合은 없습니다.

제공 툴

설치 및 배포

pip install -r requirements.txt
cp .env.example .env  # WEATHER_FORECAST_SERVICE_KEY 값 입력
python server.py

fly.io 배포:

fly launch --no-deploy
fly secrets set WEATHER_FORECAST_SERVICE_KEY=발급받은키
flyctl deploy

환경변수

지역 지정 방식

area_name(예: "서울 중구", "종로구 청운효자동") 또는 nx/ny 격자 좌표 중 하나를 지정합니다. area_name 사용 시 내장된 격자 매핑표(3,838개 행정구역)에서 3단계(읍면동) → 2단계(시군구) → 1단계(시도) 순서로 자동으로 매칭합니다.

Rate Limit

공개 서버 특성상 다음 3단계 제한이 적용됩니다:

• 분당 3회 초과 → 429

• 1시간 내 5회 위반 → 24시간 차단

• 일일 30회 초과 → 429

fly.io 멀티머신(2대) 환경에서 rate limit 카운터가 머신별로 분리될 수 있는 점은 알려진 트레이드오프로 인정합니다(가용성 우선).

실측 확인 사항

• get_vilage_fcst의 numOfRows 기본값는 1000으로 설정(예시 응답 totalCount 742~944건 실측 확인, 10이면 잘림)

• dataType=JSON 에러 응답은 실제 JSON 포맷으로 넘어옴(유효하지 않은 nx/ny 요청 시 resultCode: "10" JSON 정상 수신 확인). 단, 만약을 대비해 XML <resultCode>/<resultMsg> 정규식 폴백도 구현됨

• get_vilage_fcst에 유효하지 않은 base_time(예: 03시)을 지정하면 resultCode: "03" (NO_DATA) 오류가 나타남(빈 응답이 아닌 명시적 오류)

• 별일기예보 +4일 이후(연장기간) PCP/SNO/WSD는 정성정보 코드(1=적음/2=보통/3=많음)로 연결되어 옴을 실측 확인. 서버는 baseDate에 비해 fcstDate가 +4일 이상이면 이 코드 테이블을 적용하고 응답에 is_extended_period: true를 표시함

• get_fcst_version은 basedatetime을 base_time과 동일한 YYYYMMDDHHmm 형식으로 지정하면 정상 동작함(ftype=SHRT 기준)

라이선스

MIT

참고

• 원본 API 명세: 기상청 「단기예보 조회서비스(2.0) Open API 활용 가이드」

• 격자좌표–위경도 매핑표: 기상청 제공 Excel 자료(2026년 7월 기준, 3,838개 행정구역)

• 다음 지역만 제공(북한·국외 미제공)