Skip to main content
Glama
Sign In
deenesjakoruzh
airkorea-statistics-mcp

airkorea-statistics-mcp

by hlucent
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

⚠️ 서비스 종료 안내 본 MCP 서버는 2026-08-23부로 fly.io 배포를 종료했습니다. 코드는 개발 참고용으로 저장소에 남겨둡니다.

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 = ㎍/㎥

Related MCP server: seoul-timeavg-air-mcp

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Resources

Related MCP Connectors

Related MCP Servers

  • korea-public-data-mcp

    GeeYun086
    F
    license
    A
    quality
    B
    maintenance
    Enables Claude to query Korean public financial, economic, and statistical data (OpenDART, ECOS, KOSIS, and data.go.kr) via real API calls, providing factual answers instead of guesses.
    13
    -

  • seoul-timeavg-air-mcp

    hlucent
    A
    license
    Not graded
    quality
    C
    maintenance
    Retrieves hourly average air quality data (PM10, PM2.5, ozone, NO2, CO, SO2) from Seoul's open data platform, filtered by station or district.
    MIT

  • airkorea-forecast-alert-mcp

    hlucent
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables querying Korean air quality forecasts, weekly ultrafine dust forecasts, high-concentration PM2.5 forecasts, particulate matter alarm statuses, ozone advisories, and yellow dust advisories from the AirKorea OpenAPI.
    MIT