korea-living-weather-index-mcp

기상청이 공공데이터포털을 통해 제공하는 생활기상지수 조회서비스(4.0) (LivingWthrIdxServiceV5)를 MCP로 구현한 서버입니다. 자외선지수와 대기정체지수 예보를 전국 약 3,838개 지점(시군구~읍면동 단위) 기준으로 3시간 간격, 최대 75~78시간 후까지 조회할 수 있습니다. 추가로 행정안전부 생활안전지도(IF_0113)의 실측/현재 자외선지수도 함께 제공합니다.

기존에 운영 중이던 safemap-uv-index-mcp(행정안전부 생활안전지도 자외선지수

• 기상청 예보)의 get_uv_index 툴을 이 프로젝트로 이식해 통합했습니다. 두 프로젝트가 겹치는 기능을 갖게 되어, safemap-uv-index-mcp는 더 이상 독립적으로 확장하지 않고 이 MCP로 기능을 일원화하는 방향입니다.

제공 툴

get_uv_forecast

지점코드(areaNo)와 발표시간(time)을 기준으로 자외선지수 예보를 조회합니다. 0시간 후부터 75시간 후까지 3시간 간격 예측값을 반환합니다.

자외선지수 단계

단계	지수범위
위험	11 이상
매우높음	8~10
높음	6~7
보통	3~5
낮음	0~2

get_air_diffusion_forecast

지점코드(areaNo)와 발표시간(time)을 기준으로 대기정체지수 예보를 조회합니다. 3시간 후부터 78시간 후까지 3시간 간격 예측값을 반환합니다.

대기정체지수 단계

단계	자료값
매우높음	100
높음	75
보통	50
낮음	25

search_area_code

지역명(시/도, 시/군/구, 읍/면/동)으로 지점코드(areaNo)를 검색합니다.

get_uv_index

행정안전부 생활안전지도(IF_0113, 기상청 제공) 실측/현재 자외선지수를 시/도·시/군/구 기준으로 조회합니다. safemap-uv-index-mcp에서 이식했습니다.

주의: 이 API는 위 세 툴과 다른 API이며 areaNo 코드 체계를 쓰지 않습니다. 지역 필터 파라미터가 서버에 없어(실측 확인됨) 전국 데이터를 가져온 뒤 sido/sigungu 텍스트로 클라이언트 사이드 필터링을 수행합니다. 응답도 ctprvn_nm/signgu_nm(시도명/시군구명 문자열)로만 오며, area_codes.json의 areaNo와는 매핑되지 않습니다.

설치 및 실행

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

환경변수

변수명	설명
KMA_LIVING_WEATHER_SERVICE_KEY	공공데이터포털에서 발급받은 "기상청_생활기상지수 조회서비스(4.0)" 일반 인증키(Decoding)
SAFEMAP_API_KEY	행정안전부 생활안전지도(IF_0113) 오픈API 인증키

배포

fly.io에 배포합니다. 자세한 절차는 프로젝트 부트스트랩 문서를 따릅니다.

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

배포 후 커넥터 연결 시 /mcp 경로를 붙여서 연결합니다: https://<앱이름>.fly.dev/mcp

데이터 출처

• 제공기관: 기상청 / 행정안전부
• 플랫폼: 공공데이터포털(data.go.kr) / 생활안전지도(safemap.go.kr)
• API명: 생활기상지수 조회서비스(4.0) (LivingWthrIdxServiceV5), 생활안전지도 자외선지수(IF_0113)
• 라이선스: 공공누리 (각 플랫폼 이용약관에 따름)

알려진 제약사항 (실측 완료, 2026-08-23 기준)

• areaNo를 빈 문자열로 보내면 전체지점조회로 정상 동작함(ERROR-10 아님). 다만 응답이 매우 클 수 있어 이 옵션은 툴 파라미터로 노출하지 않았습니다. area_no 또는 area_name으로 특정 지점을 지정해 조회하세요.
• 자외선지수 응답에는 h78 필드가 포함되지 않음을 확인했습니다(h0~h75만 존재, 명세서 예제의 h78은 오기로 판단). 야간 시간대 값은 빈 문자열로 와서 결측(None) 처리됩니다.
• 대기정체지수 값은 실측 결과 정확히 25/50/75/100 중 하나로만 확인되었으나, 표본이 제한적이라 코드에는 안전하게 근사 매핑 로직(37.5/62.5/87.5 경계)을 유지하고 있습니다.
• 에러 응답도 dataType=JSON 요청 시 JSON으로 옴을 확인했습니다(XML 아님). XML 폴백 파서는 안전장치로 남겨두었습니다.
• Rate limit: 분당 3회(IP 기준), 1시간 내 5회 초과 시 24시간 차단, 일일 30회 상한 (멀티 머신 배포 시 머신 수에 비례해 실질 완화될 수 있음)

관련 프로젝트

• safemap-uv-index-mcp — 2026-08-23부로 이 프로젝트에 흡수·통합됨. 해당 프로젝트가 제공하던 get_uv_index(행안부 생활안전지도 자외선지수)와 get_uv_forecast, 지역코드 검색 기능이 모두 이 저장소로 이관되었으며, 대기정체지수 기능도 새로 추가되었다. safemap-uv-index-mcp 저장소는 참고용으로만 보관되고 fly.io 배포는 중단되었다. 앞으로 자외선지수· 대기정체지수 관련 신규 기능은 모두 이 저장소(korea-living-weather-index-mcp) 하나로 개발한다.