seoul-realtime-air-by-region-mcp

Dieser MCP-Server ruft die aktuellen Luftqualitätsdaten für die fünf Bezirke von Seoul (Zentrum/Nordosten/Südosten/Nordwesten/Südwesten) ab. Er basiert auf der RealtimeCityAir-API des Seoul Open Data Plaza.

• Bereitstellende Organisation/Abteilung: Luftqualitätspolitik-Abteilung des Klima- und Umweltbüros der Stadt Seoul

• Ursprungsdaten: Seoul Open Data Plaza – Aktuelle Luftqualität nach Bezirk in Seoul

• Lizenz (Daten): Public-Nuri-Typ 1 (Quellenangabe erforderlich, kommerzielle Nutzung und Änderung erlaubt)

• Lizenz (Code): MIT

Bereitgestellte Tools

get_realtime_air_by_region

Ruft die aktuellen Luftqualitätsdaten für einen Bezirk (oder einen bestimmten Bezirk/eine bestimmte Messstation) ab.

Rückgabefelder: Messdatum (MSRMT_DT), Bezirk (SAREA_NM), Messstation (MSRSTN_NM), Feinstaub PM10 (PM, ㎍/㎥), Feinstaub PM2.5 (FPM, ㎍/㎥), Ozon (OZON, ppm), Stickstoffdioxid (NTDX, ppm), Kohlenmonoxid (CBMX, ppm), Schwefeldioxid (SPDX, ppm), Gesamtluftqualitätsstufe (CAI_GRD), Gesamtluftqualitätsindex (CAI_IDX), Indexbestimmender Stoff (CRST_SBSTN)

list_available_regions

Gibt eine feste Liste der 5 abfragbaren Bezirksnamen (Zentrum/Nordosten/Südosten/Nordwesten/Südwesten) zurück. Kein API-Aufruf.

Related MCP server: mcp-waqi

Durch Tests bestätigte Einschränkungen

• Der Authentifizierungsschlüssel wird als URL-Pfadsegment übergeben (/{KEY}/json/RealtimeCityAir/...), nicht als Query-Parameter.

• msrstn_nm kann nicht ohne sarea_nm verwendet werden. Aufgrund der API-Pfadstruktur sind optionale Parameter fest in der Reihenfolge SAREA_NM-Position → MSRSTN_NM-Position angeordnet. Wird sarea_nm ausgelassen und nur msrstn_nm übergeben, wird dieser Wert als SAREA_NM interpretiert, was zu INFO-200 (keine Daten) führt. Dieser Server filtert Anfragen mit nur msrstn_nm vor dem API-Aufruf heraus und gibt eine klare Fehlermeldung aus.

• Ein größerer start_index/end_index-Bereich gibt tatsächlich mehrere Datensätze korrekt zurück (bei Gesamtabfrage 25 Datensätze bestätigt).

• Normale Antworten sind JSON, aber einige Fehlerantworten (z. B. Authentifizierungsschlüsselfehler INFO-100) werden trotz TYPE=json-Anfrage als XML zurückgegeben. Dieser Server verwendet einen Fallback-Parser, der bei JSON-Parsing-Fehlern die XML-Elemente <CODE>/<MESSAGE> extrahiert.

• Für den Wert CAI_GRD (Gesamtluftqualitätsstufe) wurden zum Zeitpunkt der Tests "Gut" und "Mäßig" bestätigt ("Schlecht"/"Sehr schlecht" wurden zum Testzeitpunkt nicht beobachtet, sind aber laut Spezifikation möglich).

Installation und Ausführung (Lokal)

git clone https://github.com/hlucent/seoul-realtime-air-by-region-mcp.git
cd seoul-realtime-air-by-region-mcp
pip install -r requirements.txt
cp .env.example .env  # SEOUL_API_KEY 값 입력
python server.py

Umgebungsvariablen

Bereitstellung (fly.io)

fly launch --no-deploy
fly secrets set SEOUL_API_KEY=<발급받은키>
flyctl deploy

Nach der Bereitstellung wird beim Verbinden des Claude.ai-Konnektors der Pfad /mcp wie folgt angehängt:

https://<앱이름>.fly.dev/mcp

Sicherheit

Der Server ist ohne Authentifizierungsschlüssel öffentlich zugänglich. Es gilt ein IP-basiertes 3-stufiges Rate-Limiting (3 Anfragen pro Minute – bei Multi-Maschinen-Bereitstellung kann dies proportional zur Anzahl der Maschinen abgemildert werden, 5 Verstöße pro Stunde führen zu einer 24-stündigen Sperrung, tägliches Gesamtlimit von 30 Anfragen).

Die IP wird vorrangig aus dem Fly-Client-IP-Header (vom fly.io-Edge gesetzt, vom Client nicht fälschbar) ermittelt. Der Rate-Limit-Zähler wird pro Prozess im Arbeitsspeicher (dict) geführt und nicht zwischen Maschinen geteilt. Wenn fly.io Anfragen auf mehrere Maschinen verteilt, kann sich das effektive Limit pro IP auf "3 Anfragen pro Minute × Anzahl der laufenden Maschinen" abmildern. Dies ist ein Design-Kompromiss für die In-Memory-Implementierung ohne externen Speicher.

Lizenz

MIT-Lizenz. Die ursprünglichen Daten unterliegen dem Public-Nuri-Typ 1.