airkorea-statistics-mcp

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

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

제공 기능

측정 단위: 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

환경변수

주의: 이 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 (코드 자체). 원본 데이터는 위 공공누리 라이선스를 따릅니다.