airkorea-realtime-mcp

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

Bereitgestellte Tools (5)

Related MCP server: mcp-waqi

Datenquelle

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

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

• Dienstgruppe: Korea Environment Corporation_Air Korea_Luftverschmutzungsinformationen, Korea Environment Corporation_Air Korea_Messstationsinformationen, Korea Environment Corporation_Air Korea_Integrierter Luftqualitätsindex (CAI) Abfragedienst (Dienstgruppencode B552584)

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

Messeinheiten und Klassifizierungsstandards

Grade-Werte: 1=Gut, 2=Normal, 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 korrekt sind (durch Kreuzvalidierung mit 5 verschiedenen Messstationen verifiziert). Bezugssystem: WGS84.

• Koordinatensystem der Umgebungsstationsabfrage (get_nearby_stations): Es wurde durch Messungen bestätigt, dass die direkte Eingabe von WGS84-Breiten-/Längengraden völlig falsche Ergebnisse liefert (z. B. werden bei Eingabe der Koordinaten von Gangnam-gu, Seoul, Messstationen auf Jeju Island zurückgegeben). Eine Koordinatentransformation in das TM-Mittelpunkt-System (EPSG:5181) ist zwingend erforderlich; dieser Server führt die automatische Transformation WGS84→EPSG:5181 mit pyproj durch und ruft dann die API auf (der Benutzer muss nur Breiten-/Längengrad eingeben). Bei Eingabe der Koordinaten des Gangnam-gu-Bezirksamts (37.515336, 127.049357) wurde die Gangnam-gu-Messstation mit einer Entfernung von 0,4 km als oberstes Ergebnis zurückgegeben, was die Transformationsgenauigkeit verifiziert.

• 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 (einzelne Schadstofffelder 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 erfolgreich.

• Strukturunterschied der items-Antwort: ArpltnInforInqireSvc/MsrstnInfoInqireSvc haben items als Array, während RltmKhaiInfoSvc (CAI) mit items.item eine Ebene tiefer verschachtelt ist. Der Server gleicht diesen Unterschied aus und gibt immer ein Array zurück.

• Darstellung fehlender Werte: Im Rahmen dieser Messungen (normale Luftqualitätsdaten) trat der Fall fehlender Werte mit "-" nicht auf, aber basierend auf den Spezifikationsbeispielen ist _safe_numeric so implementiert, dass es "-"/None/leere Zeichenfolgen/Gleitkommazahlen (float) alle sicher in None umwandelt (keine willkürliche Ersetzung durch 0).

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

• sidoName "Jeonnam-Gwangju": Wird normal abgerufen (berücksichtigt die Gründung der Sonderstadt Jeonnam-Gwangju im Jahr 2026, totalCount 64 Einträge 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 Aufrufen 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-stündige Sperrung

• Bei mehr als 30 Aufrufen insgesamt 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 Air-Korea-OpenAPI sehr umfangreich ist, wird sie als 3 unabhängige MCPs entwickelt:

Lizenz

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