airkorea-statistics-mcp

한국환경공단 에어코리아 대기오염통계 서비스(ArpltnStatsSvc) OpenAPI를 Claude가사용할 수 있는 MCP(Model Context Protocol) 서버로 제공합니다. 시도별/시군구별실시간 평균정보와 측정소별 일·월평균 통계를 조회할 수 있습니다.

에어코리아 3단계 분리 개발 중 마지막 단계이며, 1단계(airkorea-realtime-mcp),2단계(airkorea-forecast-alert-mcp)와 함께 사용하는 것을 전제로 합니다.

제공 기능

툴 이름	설명
`get_sido_average`	시도별 실시간 평균정보(시간/일평균) 조회
`get_sigungu_average`	시군구별 실시간 평균정보(시간/일평균) 조회
`get_station_daily_average`	측정소별 실시간 일평균 정보 조회(기간 지정)
`get_station_monthly_average`	측정소별 실시간 월평균 정보 조회(기간 지정)

측정 단위: SO2/CO/O3/NO2 = ppm, PM10/PM2.5 = ㎍/㎥

이 MCP의 범위에 대해 (중요)

대기오염통계 서비스(ArpltnStatsSvc) 소속 오퍼레이션 4개만 포함합니다. 아래 2개오퍼레이션은 원래 3단계 후보였으나, 실제로는 다른 서비스 그룹에 속해 이번 범위에서제외했습니다 (판단 근거는 DEVPLAN.md 0-1절 참고, 결정 경위는 DEVLOG.md 참고):

getTMStdrCrdnt(TM 기준좌표 조회) — 측정소정보 조회 서비스(MsrstnInfoInqireSvc)소속, 1단계(airkorea-realtime-mcp)와 같은 서비스 그룹
getUnityAirEnvrnIdexSnstiveAboveMsrstnList(통합대기환경지수 나쁨 이상 측정소목록조회) — 대기오염정보 조회 서비스(ArpltnInforInqireSvc) 소속, 1·2단계와 같은서비스 그룹

두 오퍼레이션을 1·2단계 저장소에 추가할지 여부는 별도로 논의 예정입니다(보류 상태).

설치 및 실행

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

환경변수

변수명	설명
`AIRKOREA_SERVICE_KEY`	공공데이터포털에서 발급받은 에어코리아 서비스키
`PORT`	서버 포트 (fly.io 배포 시 자동 설정)

주의: 이 MCP를 호출하려면 공공데이터포털에서 **대기오염통계 서비스(ArpltnStatsSvc)**에 대한 활용신청이 별도로 되어 있어야 합니다(서비스ID 단위 개별활용신청 필요). 신청 후 실제 반영까지 1~2시간 소요됩니다.

배포 (fly.io)

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

배포 후 커넥터 연결 주소:

https://airkorea-statistics-mcp.fly.dev/mcp

Rate Limit

인증 없이 접근 가능한 공개 서버이므로 IP 기준 3단계 rate limit이 적용됩니다:

분당 3회 초과 시 429
1시간 내 5회 위반 시 24시간 차단
일일(rolling 24h) 총 30회 초과 시 429

멀티 머신 배포 시 인메모리 카운터가 머신별로 분리되어 실질 제한이 머신 수에비례해 완화될 수 있습니다.

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

숫자 필드는 JSON 문자열로 오며 코드에서 float으로 안전 변환. 결측 표현은"-"가 아니라 빈 문자열("") 로 확인됨 (khaiValue, pm10Value 등에서관측).
getCtprvnMesureSidoLIst 응답에 khaiValue 필드가 실제로 포함됨을 확인.
sidoName=광주 또는 전남을 단독으로 넘기면 totalCount=0(데이터 없음)이반환됨 — 두 지역은 반드시 병합값 전남광주로 조회해야 정상 데이터가 옴(명세서와 다른 실제 동작).
에러 응답은 실측 범위(코드 30, 10) 내에서는 JSON으로 정상 반환됨. XML 폴백파서는 구현되어 있으나 실제 XML 에러 응답은 재현하지 못함 — 만약 향후 XML로오는 케이스가 발견되면 DEVLOG.md에 추가 기록 예정.
SERVICETIMEOUT(504)은 로컬 테스트에서 재현되지 않음 — 재시도 로직(최대 3회)은구현되어 있으나 실제 타임아웃 상황에서의 동작은 미확인.

데이터 출처

제공기관: 한국환경공단 (환경부 업무위탁기관)
플랫폼: 공공데이터포털(data.go.kr)
API명: 한국환경공단_에어코리아_대기오염통계 현황 (ArpltnStatsSvc)
라이선스: 공공누리 제1유형 (저작자표시-변경금지)

라이선스

MIT License (코드 자체). 원본 데이터는 위 공공누리 라이선스를 따릅니다.

airkorea-statistics-mcp