⚠️ サービス終了のお知らせ 本MCPサーバーは2026-08-23をもってfly.ioでのデプロイを終了しました。 コードは開発参考用としてリポジトリに残しています。

airkorea-realtime-mcp

韓国環境公団エアコリアOpenAPIのリアルタイム大気汚染情報・統合大気環境指数(CAI)・ 測定所情報を照会するMCPサーバーです。

提供ツール(5個)

Related MCP server: seoul-air-quality-mcp

データ出所

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

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

• サービスグループ: 韓国環境公団_エアコリア_大気汚染情報、韓国環境公団_エアコリア_測定所情報、 韓国環境公団_エアコリア_統合大気環境指数(CAI)照会サービス(サービスグループコード B552584)

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

測定単位および等級基準

等級(Grade)値: 1=良い、2=普通、3=悪い、4=非常に悪い

既知の制約事項(実測で確認された事項)

• 測定所リスト(search_stations)座標軸: ver=1.1で固定呼び出し時、dmX=経度、 dmY=緯度で正常に確認済み(異なる測定所5か所で交差検証完了)。WGS84基準。

• 近接測定所照会(get_nearby_stations)座標系: WGS84緯経度をそのまま入れると 完全に見当違いの結果(例: ソウル江南区の座標入力時に済州島の測定所が返される)が出ることを実測で 確認。TM中部原点(EPSG:5181)座標変換が必ず必要であり、本サーバーはpyprojで WGS84→EPSG:5181自動変換後にAPIを呼び出す(ユーザーは緯経度のみ入力すればよい)。 江南区庁の座標(37.515336, 127.049357)入力時に江南区の測定所が距離0.4kmで最上位に 返され、変換精度を検証した。

• CAI照会(get_station_cai)応答フィールド: 仕様書の表(khaiValue/khaiGrade/khaiItem)と 異なり、実際のフィールド名はcaiValue/caiGrade/caiItemである。全フィールドは stationCode、stationName、mangName、dataTime、caiValue、caiGrade、caiItem (個別汚染物質フィールドのso2Valueなどはこのオペレーションの応答には含まれない)。

• CAI照会の正常resultCode: 他の4つのオペレーションは正常時resultCode="00"だが、 getMsrstnKhaiRltmDnsty(CAI)のみ正常時resultCode="200"、resultMsg="NORMAL_CODE"で 応答する。サーバーコードはresultMsgが"NORMAL_CODE"/"NORMAL SERVICE"の場合も正常として 処理するようになっている。

• items応答構造の違い: ArpltnInforInqireSvc/MsrstnInfoInqireSvcはitemsが配列、 RltmKhaiInfoSvc(CAI)はitems.itemで一段階多くラップされている。サーバーはこの違いを 吸収して常に配列で返す。

• 欠損値の表現: 今回の実測範囲(正常な大気質データ)では"-"欠損ケースは現れ なかったが、仕様書の例に基づき_safe_numericが"-"/None/空文字列/浮動小数点数(float)すべてを Noneに安全変換するよう実装されている(0に任意置換しない)。

• APIサーバーの安定性: 実測中にSERVICETIMEOUT_ERROR(エラーコード05、HTTP 504)が頻繁に 発生することを確認。サーバーはコード05に限り最大3回まで自動再試行する。

• sidoName「全南光州」: 正常に照会される(2026年の全南光州特別市発足を反映、totalCount 64件確認)。

環境変数

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

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コネクタ接続

デプロイ完了後、アドレスの末尾に/mcpを付けて接続します。

https://airkorea-realtime-mcp.fly.dev/mcp

Rate Limitポリシー

APIキーなしでURLのみで接続可能な公開サーバーのため、IP基準の3段階rate limitが適用されます。

• 1分あたり3回超過時429 (マルチマシンデプロイ時はマシン数に比例して実質緩和される場合あり)

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

• 日次(ローリング24時間)合計30回超過時429

エラーコード

このAPIは公共データポータル標準エラーコード体系を使用します(ソウル市オープンデータ広場の INFO-000/ERROR-3xx体系とは異なります)。

関連プロジェクト

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

ライセンス

MIT (コード) / 公共ヌリ第1類型(表示)準拠 — データ出所(環境部/韓国環境公団)表記