korea-living-weather-index-mcp

기상청이 공공데이터포털을 통해 제공하는 생활기상지수 조회서비스(4.0) (LivingWthrIdxServiceV5)를 MCP로 구현한 서버입니다. 자외선지수와 대기정체지수 예보를 전국 약 3,838개 지점(시군구읍면동 단위) 기준으로 3시간 간격, 최대 7578시간 후까지 조회할 수 있습니다.

기존에 운영 중인 safemap-uv-index-mcp(행정안전부 생활안전지도 자외선지수 + 기상청 예보)와는 별개의 프로젝트입니다.

제공 툴

get_uv_forecast

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

자외선지수 단계

get_air_diffusion_forecast

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

대기정체지수 단계

search_area_code

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

Related MCP server: korea-weather-mcp

설치 및 실행

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

환경변수

배포

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

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

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

데이터 출처

• 제공기관: 기상청

• 플랫폼: 공공데이터포털(data.go.kr)

• API명: 생활기상지수 조회서비스(4.0) (LivingWthrIdxServiceV5)

• 라이선스: 공공누리 (공공데이터포털 이용약관에 따름)

알려진 제약사항 (실측 완료, 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 — 행정안전부 생활안전지도 + 기상청 자외선지수 예보 (기존 별도 운영 중)