⚠️ Hinweis zur Einstellung des Dienstes Dieser MCP-Server wurde am 2026-08-23 von fly.io zurückgezogen. Der Code bleibt zu Entwicklungsreferenzzwecken im Repository.

airkorea-statistics-mcp

Stellt die OpenAPI des Luftverschmutzungsstatistik-Dienstes (ArpltnStatsSvc) von 에어코리아 der 한국환경공단 als MCP-Server (Model Context Protocol) für Claude bereit. Echtzeit-Durchschnittsinformationen nach Provinz/Stadt und Stadt/Landkreis sowie Tages- und Monatsdurchschnittsstatistiken pro Messstation können abgerufen werden.

Es ist die letzte Stufe der dreistufigen getrennten Entwicklung von 에어코리아 und setzt die Verwendung zusammen mit Stufe 1 (airkorea-realtime-mcp) und Stufe 2 (airkorea-forecast-alert-mcp) voraus.

Bereitgestellte Funktionen

Messeinheiten: SO2/CO/O3/NO2 = ppm, PM10/PM2.5 = ㎍/㎥

Related MCP server: seoul-timeavg-air-mcp

Zum Umfang dieses MCP (Wichtig)

Es enthält nur die 4 Operationen des Luftverschmutzungsstatistik-Dienstes (ArpltnStatsSvc). Die folgenden 2 Operationen waren ursprünglich Kandidaten für Stufe 3, gehören aber tatsächlich zu anderen Dienstgruppen und wurden aus diesem Umfang ausgeschlossen (Begründung siehe DEVPLAN.md Abschnitt 0-1, Entscheidungsverlauf siehe DEVLOG.md):

• getTMStdrCrdnt (TM-Basiskoordinaten abfragen) — gehört zum Messstationsinformations-Abfragedienst (MsrstnInfoInqireSvc), gleiche Dienstgruppe wie Stufe 1 (airkorea-realtime-mcp)

• getUnityAirEnvrnIdexSnstiveAboveMsrstnList (Liste der Messstationen mit integriertem Luftumgebungsindex „schlecht“ oder höher abfragen) — gehört zum Luftverschmutzungsinformations-Abfragedienst (ArpltnInforInqireSvc), gleiche Dienstgruppe wie Stufe 1 und 2

Ob die beiden Operationen zu den Repositories der Stufen 1 und 2 hinzugefügt werden, wird separat diskutiert (Status: zurückgestellt).

Installation und Ausführung

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

Umgebungsvariablen

Hinweis: Um dieses MCP aufzurufen, muss beim 공공데이터포털 separat eine Nutzungsanmeldung für den Luftverschmutzungsstatistik-Dienst (ArpltnStatsSvc) erfolgen (individuelle Nutzungsanmeldung pro Dienst-ID erforderlich). Nach der Anmeldung dauert es 1–2 Stunden, bis sie wirksam wird.

Bereitstellung (fly.io)

fly launch --no-deploy
fly secrets set AIRKOREA_SERVICE_KEY=발급받은키
flyctl deploy

Verbindungsadresse des Connectors nach der Bereitstellung:

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

Rate Limit

Da es sich um einen öffentlichen Server ohne Authentifizierung handelt, gilt ein dreistufiges Rate-Limit auf IP-Basis:

• 429 bei mehr als 3 Aufrufen pro Minute

• 24 Stunden Sperre bei 5 Verstößen innerhalb einer Stunde

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

Bei einer Multi-Machine-Bereitstellung werden die In-Memory-Zähler pro Maschine getrennt, sodass die tatsächliche Begrenzung proportional zur Anzahl der Maschinen gelockert werden kann.

Bekannte Einschränkungen (durch Messungen bestätigt, 2026-08-23)

• Numerische Felder kommen als JSON-Strings und werden im Code sicher in float konvertiert. Fehlende Werte werden nicht als "-", sondern als leere Zeichenkette ("") bestätigt (beobachtet bei khaiValue, pm10Value usw.).

• Bestätigt, dass die Antwort von getCtprvnMesureSidoLIst tatsächlich das Feld khaiValue enthält.

• Wenn sidoName=광주 oder 전남 allein übergeben wird, wird totalCount=0 (keine Daten) zurückgegeben — die beiden Regionen müssen mit dem zusammengeführten Wert 전남광주 abgefragt werden, um korrekte Daten zu erhalten (abweichendes tatsächliches Verhalten von der Spezifikation).

• Fehlerantworten werden im gemessenen Bereich (Code 30, 10) normal als JSON zurückgegeben. Ein XML-Fallback-Parser ist implementiert, aber eine tatsächliche XML-Fehlerantwort konnte nicht reproduziert werden — falls künftig ein Fall mit XML auftritt, wird er in DEVLOG.md zusätzlich dokumentiert.

• SERVICETIMEOUT (504) konnte in lokalen Tests nicht reproduziert werden — die Wiederholungslogik (maximal 3 Versuche) ist implementiert, aber das Verhalten in einer tatsächlichen Timeout-Situation ist unbestätigt.

Datenquelle

• Bereitstellende Organisation: 한국환경공단 (vom Umweltministerium beauftragte Organisation)

• Plattform: 공공데이터포털 (data.go.kr)

• API-Name: 한국환경공단_에어코리아_대기오염통계 현황 (ArpltnStatsSvc)

• Lizenz: 공공누리 제1유형 (Namensnennung-Keine Bearbeitung)

Lizenz

MIT-Lizenz (der Code selbst). Die Originaldaten unterliegen der oben genannten 공공누리-Lizenz.