airkorea-forecast-alert-mcp

这是一个查询한국환경공단 에어코리아 OpenAPI 的空气质量预报 · 可吸入颗粒物警报 · 臭氧/黄沙注意报系列数据的 MCP 服务器。

提供工具

设计注记: DEVPLAN.md 第3部分以及존주의보·黄沙注意报合在在一个工具（通过 advisory_type 参数分支）的方案进行了优先审核，但实测结果为两operations的response字段差异很大（臭氧为浓度、发布阶段等8个字段，黄沙为座次、地区文字等2个字段），若合并会影响使用性，因此拆分为2个工具（共6个）。

Related MCP server: seoul-timeavg-air-mcp

数据来源

• 分发主体: 한국환경공단 기후대기본부 대기환경처 대기환경정책지원부

• 平台: 공공데이터포털 (data.go.kr)

• 服务群: 韩国环境공단_에어코리아_대기浩염정보(部分)，한국환경공단_에어코리아_ 高浓度超细颗粒物（超过50）预报信息，한국환경공단_에어코리아_可吸入颗粒物警报发布现状， 한국환경공단_에어코리아_臭氧황사 발생信息（服务群代码 B552584）

• 许可范围: 署名-禁止演绎（Attribution-NoDerivatives），必须标注（환경부/한국환경공단）数据来源

公布周期（사항）

已知限制事项（사실 또는 사항, 작업 항목, 2026-08-22/23 test payload）

get_air_quality_forecast（getMinuDustFrcstDspth）

• informData 字段确认实际存在。items로 측성 아이템 각 항목이今天/明天/后天 각각의预报에 해당하며,该字段의 informData 값（YYYY-MM-DD）해당 항목의 대상 날짜 표시。만약 예 Sample: dataTime는 2026-08-22 23시의 발표이며，items의 informData 의 값은 "2026-08-22"/"2026-08-23"/"2026-08-24" 순으로 옵니다

• 臭氧（O3）赛季外（11~3월）查询時 reply 없이 정상적으로 빈 목록（resultCode: "00", totalCount: 0）（2026-01-15 실측 확인）

• 此次测试未使用 ver=1.1 参数（仅用 기본/구版本方式确认 잘 됨）. 이미지 URL（imageUrl1~imageUrl9는 검증용 링크로 그대로 반환합니다.

get_high_pm25_forecast（getMinuFrcstDspth50Over）

• 规格书没有规格表（SWAGGER文档 참고만）所以全部实测加以确认。

• searchDate、informCode（PM10/PM25/O3）参数正常响应 확인。

• 있는 19개 area {지역}50Over 필드명 pointed（실측 확인，alphabetical order）: busan50Over, chungbuk50Over, chungnam50Over, daegu50Over, daejeon50Over, gwangju50Over, gyeongbuk50Over, gyeonggibuk50Over, gyeongginam50Over, gyeongnam50Over, incheon50Over, jeju50Over, jeonbuk50Over, jeonnam50Over, sejong50Over, seoul50Over, ulsan50Over, youngdong50Over, youngseo50Over （同样文本 patterns에도 `{지역}Grade field exists，提供 very good/普通/ 좋음/나쁘/매우나빔 텍스트）。

• ⚠️ 베이 라（미해결）: 当 non-exceedance value "X"是实测中 확인，但未知，exceedance valueд"O"是从说明내용推断한 것인데，2026年8月（계절적으로 PM2.5 低季） 한 달에서 재현되지 않는 깨진 상태。代码中使用默认推信息"O"，实高 valued高浓度 상태时如实해 예상입니다.

• 查詢 가능 기간이 최근作る 1개月로 확인됨（그 이전 date searchDate로 조회하면 totalCount: 0 빈 목록）.

get_pm_alarm_status（getUlfptcaAlarmInfo）

• 아직 해제 not 되어 있지 않은 경보는 Description대로 대개 clearDate에는 "--", clearTime에는 ":00", clearVal는 "공учет"（数字 아닌）으로 돌아며，这工具正此将它み交给 safe 변환하면 null로 처리하고，另外로 cleared（bool）/status（string）字段에 "미해제（진행 중）" status를 表示 -- 할 수 있습니다.

• ⚠️ pretend（미해결）: Q5~2026实际数据（총 448件）整体 조회한结果 모든 items당 expected완료 경활였고，미해제 pattern（"--"/"공공"）이 실제로 보이는 사례를 발견 못했습니다. 今后 미해제 警报出现需重新验证.

get_ozone_advisory / get_yellowdust_advisory

• 오존주의보는 每年 4月~10月期间发布的季节性性합니다（비시즌 데이터가 없는 전적으로,上述 get_air_quality_forecast O3 비시즌 test에서 API itself는 정상자동원자동→별도확인）。

• get_ozone_advisory, get_yellowdust_advisory를 통해 year 파라미터를 활용한 정상 호출 확인（2026/2025년）。

논 общего: 공공데이터MIT API 자체의 intermittent 달, 핵심불량

• 测试 중 getMinuDustFrcstDspth, getMinuDustWeekFrcstDspth, getMinuDustFrcstDspth50Over에서 Typime **间歇性오류 SERVICETIMEOUT_ERROR（코드 05）；또는 순수 network timeout 열차在宕。재시는데大多恢复正常响应 — 이 not code issue인 공공데이터 포탈 server의 부하问题.

• 사용자 client uses httpx 30초 timeout, 권장사용하는 재시도 필요 과도할 때.

환경 변수

설치及 실행

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

배津贴 (fly.io)

fly launch --no-deploy
# fly.toml이 [http_service] 방식인지 확인 후
fly secrets set AIRKOREA_SERVICE_KEY=발급받은키
flyctl deploy

Claude.ai 커넥터 연결

https://airkorea-forecast-alert-mcp.fly.dev/mcp

Rate Limit 政策

• 分钟>3 次 → 429（또는 다중 호스트 배포 시 실 scale，기종比로 실질 완화될 수 있음）

• 1시간 中 429 5 이상 수신时 24시간 차단

• 日（rolling 24시간）总 30회 초과시 429

错误代码

공公开데이터포털 핵심 에러 코드体系 사용한다（1단계 airkorea-realtime-mcp처럼 동일）.

관련 프로젝트

에어코리아 OpenAPI 넓으므로独立 세个별해separate MCP로 관리：

License

MIT（코plicit code) / 遵守공공누리第1型（署名） — 출처(환경부/한국환경공단) 표시