airkorea-forecast-alert-mcp

Dies ist ein MCP-Server zum Abrufen der **Luftqualitätsvorhersage-, Feinstaubwarn- und Ozon-/Sandsturmwarnungs-**Serie der AirKorea-OpenAPI der Korea Environment Corporation.

Bereitgestellte Tools

Designhinweis: In Abschnitt 3 der DEVPLAN.md wurde zunächst geprüft, Ozon- und Sandsturmwarnungen in einem Tool (mit advisory_type-Parameter) zusammenzufassen. Da sich die Antwortfelder der beiden Operationen jedoch stark unterscheiden (Ozon: 8 Felder wie Konzentration, Warnstufe usw.; Sandsturm: 2 Textfelder für Runde und Region), haben wir uns entschieden, sie in 2 separate Tools aufzuteilen (insgesamt 6 Tools), da eine Zusammenfassung die Benutzerfreundlichkeit beeinträchtigen würde.

Related MCP server: seoul-timeavg-air-mcp

Datenquelle

• Bereitstellende Organisation: Abteilung für Luftqualitätspolitik, Amt für Luftqualitätsumwelt, Klima- und Luftqualitätshauptquartier der Korea Environment Corporation

• Plattform: Öffentliches Datenportal (data.go.kr)

• Dienstleistungsgruppe: Korea Environment Corporation_AirKorea_Luftverschmutzungsinformationen (teilweise), Korea Environment Corporation_AirKorea_Vorhersageinformationen für hohe PM2,5-Konzentrationen (über 50), Korea Environment Corporation_AirKorea_Feinstaubwarnstatus, Korea Environment Corporation_AirKorea_Ozon-/Sandsturm-Informationen (Dienstleistungsgruppencode B552584)

• Nutzungslizenz: Namensnennung-Keine Bearbeitung (Verpflichtung zur Angabe der Datenquelle (Umweltministerium/Korea Environment Corporation) einhalten)

Veröffentlichungszyklus (wichtig)

Bekannte Einschränkungen (durch Messungen bestätigte Punkte, pro Operation – Messung vom 22./23.08.2026)

get_air_quality_forecast (getMinuDustFrcstDspth)

• Das Feld informData wurde tatsächlich bestätigt. Jedes Element im items-Array unterscheidet die Vorhersage für heute/morgen/übermorgen, und der informData-Wert (JJJJ-MM-TT) gibt das Zieldatum der jeweiligen Vorhersage an. (Beispiel: Wenn dataTime "Veröffentlicht am 22.08.2026 um 23 Uhr" ist, kommen die items in der Reihenfolge informData "2026-08-22"/"2026-08-23"/"2026-08-24")

• Bei Abfrage außerhalb der Ozon(O3)-Saison (November–März) wird ohne Fehler normal eine leere Liste (resultCode: "00", totalCount: 0) zurückgegeben (durch Messung am 15.01.2026 bestätigt).

• Der Parameter ver=1.1 wurde bei dieser Messung nicht verwendet (die Standard-/Altversion funktioniert nachweislich ausreichend). Die Bild-URLs (imageUrl1–imageUrl9) werden als Referenzlinks unverändert zurückgegeben.

get_high_pm25_forecast (getMinuDustFrcstDspth50Over)

• Da es in der Spezifikation keine Spezifikationstabelle gibt (nur Verweis auf das SWAGGER-Dokument), wurde alles durch Messungen bestätigt.

• Die Parameter searchDate, informCode (PM10/PM25/O3) funktionieren nachweislich normal.

• Alle 19 Regionsfeldnamen {Region}50Over (durch Messung bestätigt, alphabetisch): busan50Over, chungbuk50Over, chungnam50Over, daegu50Over, daejeon50Over, gwangju50Over, gyeongbuk50Over, gyeonggibuk50Over, gyeongginam50Over, gyeongnam50Over, incheon50Over, jeju50Over, jeonbuk50Over, jeonnam50Over, sejong50Over, seoul50Over, ulsan50Over, youngdong50Over, youngseo50Over (Die gleichnamigen {Region}Grade-Felder werden ebenfalls bereitgestellt und enthalten die Texte gut/mäßig/schlecht/sehr schlecht).

• ⚠️ Zu überprüfen (ungelöst): Dass der Wert bei Nicht-Überschreitung "X" ist, wurde durch Messung bestätigt. Der Wert bei Überschreitung (in der Spezifikation vermuteter Wert "O") konnte jedoch im August 2026 (saisonal niedrige PM2,5-Zeit) nicht reproduziert werden und bleibt unbestätigt. Im Code ist der in der Spezifikation vermutete Wert ("O") als Standardwert hinterlegt; eine erneute Verifizierung bei tatsächlichem Auftreten hoher Konzentrationen ist erforderlich.

• Der abfragbare Zeitraum ist auf ca. den letzten Monat begrenzt (durch Messung bestätigt – bei Abfrage mit searchDate vor diesem Zeitraum wird eine leere Liste mit totalCount: 0 zurückgegeben).

get_pm_alarm_status (getUlfptcaAlarmInfo)

• Laut Spezifikation haben noch nicht aufgehobene Warnungen clearDate als "--", clearTime als ":00" und clearVal als "공람" (keine Zahl). Dieses Tool behandelt diese Felder in solchen Fällen bei der sicheren Konvertierung als null und kennzeichnet den Status "nicht aufgehoben (laufend)" separat über die Felder cleared (bool)/status (String).

• ⚠️ Zu überprüfen (ungelöst): Bei der vollständigen Abfrage der tatsächlichen Daten von 2025–2026 (insgesamt 448 Fälle) waren alle bereits vollständig aufgehoben; es konnte kein Fall gefunden werden, in dem das Muster für nicht aufgehobene Warnungen ("--"/"공람") tatsächlich auftrat. Eine erneute Verifizierung bei zukünftigem Auftreten nicht aufgehobener Warnungen ist erforderlich.

get_ozone_advisory / get_yellowdust_advisory

• Ozonwarnungen werden nur von April bis Oktober jährlich veröffentlicht (außerhalb der Saison gibt es einfach keine Daten; bei der O3-Messung außerhalb der Saison von get_air_quality_forecast wurde separat bestätigt, dass die API selbst normal funktioniert).

• Sowohl get_ozone_advisory als auch get_yellowdust_advisory wurden mit dem Parameter year erfolgreich getestet (2026/2025).

Gemeinsam: Gelegentliche Instabilität der öffentlichen Datenportal-API selbst

• Bei den Messungen traten bei Aufrufen von getMinuDustFrcstDspth, getMinuDustWeekFrcstDspth und getMinuDustFrcstDspth50Over gelegentlich SERVICETIMEOUT_ERROR (Code 05) oder reine Netzwerk-Timeouts auf. Bei erneuten Versuchen derselben Anfrage wurden meist normale Antworten empfangen – dies ist kein Codefehler, sondern ein Lastproblem des öffentlichen Datenportal-Servers selbst. Der Client verwendet ein 30-Sekunden-Timeout mit httpx; dem Aufrufer wird empfohlen, bei Bedarf erneut zu versuchen.

Umgebungsvariablen

Installation und Ausführung (lokal)

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

Bereitstellung (fly.io)

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

Claude.ai-Connector-Verbindung

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

Rate-Limit-Richtlinie

• 429 bei mehr als 3 Aufrufen pro Minute (bei Multi-Machine-Bereitstellung kann dies proportional zur Maschinenanzahl praktisch abgemildert werden)

• Bei 5 oder mehr 429-Antworten innerhalb einer Stunde: 24-Stunden-Sperre

• 429 bei mehr als insgesamt 30 Aufrufen pro Tag (rollierend 24 Stunden)

Fehlercodes

Es wird das Standard-Fehlercodesystem des öffentlichen Datenportals verwendet (identisch mit Stufe 1 airkorea-realtime-mcp).

Verwandte Projekte

Da die AirKorea-OpenAPI sehr umfangreich ist, wird sie als 3 unabhängige MCPs entwickelt:

Lizenz

MIT (Code) / Einhaltung der Public-Nuri-Typ-1-Lizenz (Namensnennung) – Angabe der Datenquelle (Umweltministerium/Korea Environment Corporation)