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 참고):

• getTMStdCrdnt(TM 기준좌표 조회) — 측정소정보 조회 서비스(MsrstnInfoInqireSvc) 소속, 1단계(airkorea-realtime-mcp)와 같은 서비스 그룹

• getUnityAirInqireList(통합대기환경지수 나쁨 이상 측정소 목록 조회) — 대기오염정보 수집 서비스(ArltnInforInqireSvc) 소속, 1·2단계와 같은 서비스 그룹

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

설치 및 실행

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

환경변수

| 변수명 | 설명 | | ---------------- | -- -- | | AIRKOREA_SERVICE_KEY | 공공데이터포털에서 발급받은 Air Korea 서비스 키 | | 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시간 차단

• 일일(롤링 24시간) 총 30회 초과 시 429

멀티 머신 배포 시 in-memory counter가 머신별로 분리되므로 실제 제한이 머신 수에 비해 완화될 수 있습니다.

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

• 숫자 필드는 JSON 문자열로 오며 코드에서 안전하게 float으로 변환됩니다. 결측 표현은 "-"가 아니라 빈 문자열("") 로 확인됨 (khai value, pm10Value 등에서 관측).

• getCtprvnMeasurementSidoLIst 응답에 khaiValue 필드가 실제로 포함됨을 확인했습니다.

• sidoName=광주 또는 전남을 단독으로 사용하면 totalCount=0(데이터 없음)이 반환 — 두 지역은 반드시 병합값 전남광주로 조회해야 정상 데이터가 전송됩니다 (명세서와 다른 실제 동작).

• 에러 응답은 실제 측정 범위(코드 30, 10) 내에서는 JSON으로 정상 반환됩니다. XML 폴백 파서는 구현되어 있지만 실제 XML 에러 응답은 재현하지 못했습니다 — 그 이후 XML로 응답이 오는 케이스가 발견되면 DEVLOG.md에 추가 기록 예정입니다.

• SERVICETIMEOUT(504)은 로컬 테스트에서 재현되지 않았습니다 — 재시도 로직(최대 3회)은 구현되어 있지만, 실제 시간 초과 상황에서의 동작은 미확인입니다.

데이터 출처

• 제공기관: 한국환경공단 (환경부 위탁기관)

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

• API명: 한국환경공단에어코리아대기오염통계 현황 (ArpltnStatsSvc)

• 라이선스: 공공누리 제1유형 (저작자표시-변경금지)

라이선스

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