seoul-timeavg-air-mcp

Ein MCP(Model Context Protocol) Server zum Abrufen von stündlichen Durchschnittsdaten der Luftqualität in Seoul für verschiedene Zeiträume. Er liefert stündliche Durchschnittsdaten für Feinstaub (PM10), Feinstaub (PM2.5), Ozon, Stickstoffdioxid, Kohlenmonoxid und Schwefeldioxid auf Stations-/Gebietsebene.

Datenquellen

• Bereitstellende Stelle: Abteilung Luftqualitätspolitik des Klima- und Umweltamtes der Stadt Seoul

• Plattform: Seoul Open Data Plaza — Service-ID: OA-221, Servicename: 서울시 기간별 시간평균 대기환경 정보 (TimeAverageCityAir)

• Nutzungslizenz: Öffentliche Lizenz Typ 1 (Namensnennung, kommerzielle Nutzung und Änderung erlaubt)

Bereitgestellte Werkzeuge (Tools)

get_time_average_air

Ruft die stündlichen Durchschnittsdaten der Luftqualität für einen angegebenen Messzeitpunkt (YYYYMMDDHHmm) ab.

• msrmt_dt (erforderlich): Messzeitpunkt, Format YYYYMMDDHHmm mit 12 Stellen, Minuten (mm) immer 00 (z.B. 202401011200). Mit 10 Stellen (YYYYMMDDHH) werden keine Ergebnisse abgerufen.

• start_index (optional, Standard 1): Startposition der Abfrage

• end_index (optional, Standard 25): Endposition der Abfrage (maximal 1000 Datensätze pro Abfrage)

• sarea_nm (optional): Gebietsname (z.B. Innenstadt, Nordwest)

• msrstn_nm (optional): Stationsname (z.B. Jongno-gu, Yongsan-gu)

Rückgabefelder: Messzeitpunkt, Gebietscode/-name, Stationscode/-name, Feinstaub 1h (㎍/㎥), Feinstaub 24h (㎍/㎥), Feinstaub PM2.5 (㎍/㎥), Ozon (ppm), Stickstoffdioxid (ppm), Kohlenmonoxid (ppm), Schwefeldioxid (ppm)

search_stations

Durchsucht die Luftqualitätsdaten zu einem bestimmten Zeitpunkt nach Stationsname oder Gebietsname.

• msrmt_dt (erforderlich)

• sarea_nm (optional)

• msrstn_nm (optional)

Installation und lokale Ausführung

git clone https://github.com/hlucent/seoul-timeavg-air-mcp.git
cd seoul-timeavg-air-mcp
pip install -r requirements.txt
cp .env.example .env
# .env에 SEOUL_API_KEY=발급받은키 입력
python server.py

Umgebungsvariablen

Bereitstellung (fly.io)

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

Verbindungsadresse für den Claude.ai Connector nach der Bereitstellung:

https://seoul-timeavg-air-mcp.fly.dev/mcp

Bekannte Einschränkungen

• Der Authentifizierungsschlüssel wird nicht als Query-Parameter, sondern als URL-Pfadsegment übergeben (http://openAPI.seoul.go.kr:8088/{KEY}/{TYPE}/TimeAverageCityAir/...).

• Die maximale Anzahl von Datensätzen pro Abfrage beträgt 1000 (END_INDEX - START_INDEX ≤ 1000, bei Überschreitung ERROR-336). Bei Verwendung des Beispielschlüssels (sample) sind maximal 5 Datensätze möglich (ERROR-335).

• MSRMT_DT wird nur mit 12 Stellen (YYYYMMDDHHmm, Minuten immer 00) korrekt abgefragt. Bei 10 Stellen wird INFO-200 (keine Daten) zurückgegeben.

• Tatsächliches Verhalten bei Kombination optionaler Parameter (Gebietsname/Stationsname):

  • Beide weggelassen: Alle Daten zurückgegeben

  • Nur sarea_nm angegeben: Korrekte Filterung nach Gebiet

  • Nur msrstn_nm angegeben (Gebietsname weggelassen): Es wurde ein API-spezifisches Verhalten festgestellt, bei dem der Filter ignoriert und alle Daten zurückgegeben werden. Dieser Server erkennt diesen Fall und filtert die Antwort erneut nach Stationsnamen.

  • Beide angegeben: Korrekte Filterung (Schnittmenge)

• HTTPS wird nicht unterstützt (Verbindungsfehler). Es wird nur HTTP (Port 8088) verwendet.

• Einige Fehlerantworten (z.B. ERROR-335, ERROR-336) werden auch bei TYPE=json-Anfragen als XML zurückgegeben. Dieser Server versucht zuerst JSON-Parsing und fällt bei Fehlschlag auf XML zurück.

• Da dieser Server ohne API-Schlüssel von jedem über den Connector verbunden werden kann, gilt ein IP-basiertes Rate-Limit (3 Anfragen pro Minute, bei 5 oder mehr 429-Fehlern innerhalb einer Stunde 24-stündige Sperrung, tägliches Limit von 30 Anfragen).

Lizenz

• Code: MIT License

• Daten: Öffentliche Lizenz Typ 1 (Namensnennung, Stadt Seoul)