airkorea-forecast-alert-mcp

韓国環境公団エアコリアOpenAPIの大気質予報・微細粉塵警報・オゾン/黄砂注意報系を 照会するMCPサーバーです。

提供ツール

設計ノート: DEVPLAN.md 3節ではオゾン注意報・黄砂注意報を1つのツール(advisory_type パラメータで分岐)にまとめる案を優先検討するよう指示されていましたが、実測の結果、2つのオペレーションの応答 フィールドが大きく異なり(オゾンは濃度・発令段階など8フィールド、黄砂は回次・地域テキスト2フィールド)、 1つにまとめると使い勝手が低下すると判断し、2つのツールに分離しました(計6ツール)。

Related MCP server: seoul-timeavg-air-mcp

データ出典

• 提供機関: 韓国環境公団気候大気本部大気環境処大気政策支援部

• プラットフォーム: 公共データポータル (data.go.kr)

• サービスグループ: 韓国環境公団_エアコリア_大気汚染情報(一部)、韓国環境公団_エアコリア_ 高濃度超微細粉塵(50超過)予報情報、韓国環境公団_エアコリア_微細粉塵警報発令現況、 韓国環境公団_エアコリア_オゾン黄砂発生情報 (サービスグループコード B552584)

• 利用許容範囲: 著作者表示-変更禁止 (資料の出典(環境部/韓国環境公団)表記義務遵守)

発表周期 (重要)

既知の制約事項 (実測で確認された事項、オペレーション別 — 2026-08-22/23実測)

get_air_quality_forecast (getMinuDustFrcstDspth)

• informDataフィールド実際に存在することを確認。items配列の各項目が今日/明日/明後日の予報を 区別し、informData値(YYYY-MM-DD)が該当予報の対象日付を示します。 (例: dataTimeが「2026-08-22 23時発表」の場合、itemsがinformData 「2026-08-22」/「2026-08-23」/「2026-08-24」の順で来る)

• オゾン(O3)非シーズン(11~3月)照会時、エラーなしで正常に空リスト(resultCode: "00"、 totalCount: 0)が返ります(2026-01-15実測確認)。

• ver=1.1パラメータは今回の実測では使用していません(基本/旧バージョン方式で十分に 動作確認済み)。画像URL(imageUrl1~imageUrl9)は参考用リンクとしてそのまま返します。

get_high_pm25_forecast (getMinuDustFrcstDspth50Over)

• 仕様書にスペック表がなく(SWAGGER文書参照のみ記載)全量実測で確定しました。

• searchDate、informCode(PM10/PM25/O3)パラメータ正常動作確認済み。

• 19圏域の{地域}50Overフィールド名全体(実測確認、アルファベット順): busan50Over, chungbuk50Over, chungnam50Over, daegu50Over, daejeon50Over, gwangju50Over, gyeongbuk50Over, gyeonggibuk50Over, gyeongginam50Over, gyeongnam50Over, incheon50Over, jeju50Over, jeonbuk50Over, jeonnam50Over, sejong50Over, seoul50Over, ulsan50Over, youngdong50Over, youngseo50Over (同じ名前パターンの{地域}Gradeフィールドも一緒に提供され、良い/普通/悪い/非常に悪いテキスト)。

• ⚠️ 確認必要(未解決): 未超過時の値が"X"であることは実測確認済みですが、超過時の値(仕様書 本文推定値"O")は2026年8月1か月間(季節的にPM2.5が低い時期)再現されず 未確認の状態です。コードでは仕様書推定値("O")をデフォルト値としており、 実際の高濃度発生時に再検証が必要です。

• 照会可能期間が直近約1か月に制限されることを実測確認(それ以前の日付の searchDateで照会するとtotalCount: 0の空リスト)。

get_pm_alarm_status (getUlfptcaAlarmInfo)

• まだ解除されていない警報は、仕様書上clearDateが"--"、clearTimeが":00"、 clearValが"공람"(数字ではない)で来るとされています。このツールはこの場合、該当 フィールドを安全変換時にnullとして処理し、別途cleared(bool)/status(文字列)フィールドで 「未解除(進行中)」状態を明示します。

• ⚠️ 確認必要(未解決): 2025~2026年の実際のデータ(計448件)を全量照会しましたが、全て すでに解除完了状態であり、未解除パターン("--"/"공람")が実際に再現される事例を見つけられませんでした。 今後未解除警報発生時に再検証が必要です。

get_ozone_advisory / get_yellowdust_advisory

• オゾン注意報は毎年4月~10月にのみ発表される季節性があります(非シーズンデータは単に ないだけで、上記get_air_quality_forecastのO3非シーズン実測でAPI自体は正常 動作することを別途確認しました)。

• get_ozone_advisory、get_yellowdust_advisoryともにyearパラメータで実測正常 呼び出し確認済み(2026年/2025年)。

共通: 公共データポータルAPI自体の断続的な不安定性

• 実測中、getMinuDustFrcstDspth、getMinuDustWeekFrcstDspth、 getMinuDustFrcstDspth50Over呼び出しで断続的にSERVICETIMEOUT_ERROR(コード05) または純粋なネットワークタイムアウトが発生しました。同じリクエストを再試行すると大半が正常 応答を受けました — コード欠陥ではなく公共データポータルサーバー自体の負荷性の問題と 判断されます。クライアントはhttpx30秒タイムアウトを使用し、必要に応じて呼び出し元が再試行することを 推奨します。

環境変数

インストールおよび実行 (ローカル)

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 (マルチマシンデプロイ時はマシン数に比例して実質緩和される場合あり)

• 1時間以内に429を5回以上受信すると24時間ブロック

• 日次(rolling 24時間)合計30回超過時429

エラーコード

公共データポータル標準エラーコード体系を使用します (1段階airkorea-realtime-mcpと同一)。

関連プロジェクト

エアコリアOpenAPIは規模が大きいため、3つの独立MCPに分離開発されます:

ライセンス

MIT (コード) / 公共ヌリ第1類型(著作者表示)遵守 — データ出典(環境部/韓国環境公団)表記