⚠️ Hinweis zur Einstellung des Dienstes Dieser MCP-Server hat seine fly.io-Bereitstellung am 23.08.2026 eingestellt. Der Code bleibt zu Entwicklungszwecken im Repository erhalten.

airkorea-realtime-mcp

Dies ist ein MCP-Server zum Abrufen der Echtzeit-Luftverschmutzungsinformationen, des integrierten Luftqualitätsindex (CAI) und der Messstationsinformationen der AirKorea-OpenAPI der Korea Environment Corporation.

Bereitgestellte Tools (5)

Related MCP server: seoul-air-quality-mcp

Datenquelle

• Bereitstellende Stelle: Korea Environment Corporation, Climate & Air Quality Bureau, Air Quality Policy Support Division

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

• Dienstgruppe: Korea Environment Corporation_AirKorea_Luftverschmutzungsinformationen, Korea Environment Corporation_AirKorea_Messstationsinformationen, Korea Environment Corporation_AirKorea_Integrierter Luftqualitätsindex (CAI) Abrufdienst (Dienstgruppencode B552584)

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

Messeinheiten und Klassengrenzen

Klassenwert (Grade): 1=Gut, 2=Mäßig, 3=Schlecht, 4=Sehr schlecht

Bekannte Einschränkungen (durch Messungen bestätigt)

• Koordinatenachsen der Messstationsliste (search_stations): Bei festem Aufruf mit ver=1.1 wurde bestätigt, dass dmX=Längengrad und dmY=Breitengrad sind (durch Kreuzvalidierung mit 5 verschiedenen Messstationen verifiziert). Bezugssystem: WGS84.

• Koordinatensystem der Umgebungsstationsabfrage (get_nearby_stations): Durch Messungen wurde bestätigt, dass die direkte Eingabe von WGS84-Breiten-/Längengraden völlig falsche Ergebnisse liefert (z. B. werden bei Eingabe von Koordinaten des Bezirks Gangnam in Seoul Messstationen auf der Insel Jeju zurückgegeben). Eine Koordinatentransformation auf TM-Mittelmeridian (EPSG:5181) ist zwingend erforderlich; dieser Server führt mit pyproj eine automatische WGS84→EPSG:5181-Transformation durch, bevor die API aufgerufen wird (der Benutzer muss nur Breiten-/Längengrad eingeben). Bei Eingabe der Koordinaten des Bezirksamts Gangnam (37.515336, 127.049357) wurde die Messstation von Gangnam mit einer Entfernung von 0,4 km an oberster Stelle zurückgegeben, wodurch die Transformationsgenauigkeit verifiziert wurde.

• Antwortfelder der CAI-Abfrage (get_station_cai): Abweichend von der Spezifikationstabelle (khaiValue/khaiGrade/khaiItem) lauten die tatsächlichen Feldnamen caiValue/caiGrade/caiItem. Die vollständigen Felder sind stationCode, stationName, mangName, dataTime, caiValue, caiGrade, caiItem (Felder für einzelne Schadstoffe wie so2Value sind in der Antwort dieser Operation nicht enthalten).

• Normaler resultCode der CAI-Abfrage: Die anderen 4 Operationen liefern bei Erfolg resultCode="00", aber nur getMsrstnKhaiRltmDnsty (CAI) antwortet bei Erfolg mit resultCode="200" und resultMsg="NORMAL_CODE". Der Servercode behandelt auch Fälle, in denen resultMsg "NORMAL_CODE"/"NORMAL SERVICE" ist, als Erfolg.

• Unterschied in der items-Antwortstruktur: Bei ArpltnInforInqireSvc/MsrstnInfoInqireSvc ist items ein Array, während RltmKhaiInfoSvc (CAI) eine weitere Verschachtelungsebene mit items.item aufweist. Der Server gleicht diesen Unterschied aus und gibt immer ein Array zurück.

• Darstellung fehlender Werte: Im aktuellen Messbereich (normale Luftqualitätsdaten) trat der Fall fehlender Werte mit "-" nicht auf, aber basierend auf dem Spezifikationsbeispiel ist _safe_numeric so implementiert, dass "-"/None/leere Zeichenfolgen/Gleitkommazahlen (float) alle sicher in None umgewandelt werden (keine willkürliche Ersetzung durch 0).

• Stabilität des API-Servers: Während der Messungen wurde bestätigt, dass SERVICETIMEOUT_ERROR (Fehlercode 05, HTTP 504) häufig auftritt. Der Server versucht bei Code 05 automatisch bis zu 3 Wiederholungen.

• sidoName "전남광주": Wird normal abgerufen (reflektiert die Gründung der Sonderstadt Jeonnam-Gwangju im Jahr 2026, totalCount 64 Datensätze bestätigt).

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

Verbindung mit dem Claude.ai-Connector

Nach Abschluss der Bereitstellung wird /mcp an die Adresse angehängt und verbunden.

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

Rate-Limit-Richtlinie

Da es sich um einen öffentlichen Server handelt, der ohne API-Schlüssel nur über die URL verbunden werden kann, gilt ein 3-stufiges Rate-Limit auf IP-Basis.

• Bei mehr als 3 Anfragen pro Minute: 429 (bei Multi-Machine-Bereitstellung kann dies proportional zur Anzahl der Maschinen praktisch abgemildert werden)

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

• Bei mehr als insgesamt 30 Anfragen pro Tag (rollierendes 24-Stunden-Fenster): 429

Fehlercodes

Diese API verwendet das Standard-Fehlercodesystem des Öffentlichen Datenportals (unterscheidet sich vom INFO-000/ERROR-3xx-System des Open-Data-Portals der Stadt Seoul).

Verwandte Projekte

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

Lizenz

MIT (Code) / Einhaltung von KOGL Typ 1 (Namensnennung) — Angabe der Datenquelle (Umweltministerium/Korea Environment Corporation)