weather-forecast-mcp

Dieses MCP stellt den Kurzfrist-Wettervorhersage-Abrufdienst (VilageFcstInfoService_2.0) der Korea Meteorological Administration (KMA) als MCP- (Model Context Protocol) Server bereit. Die vier Operationen – Ultrakurzfrist-Beobachtung, Ultrakurzfrist- Vorhersage, Kurzfristvorhersage und Vorhersageversion – können wahlweise über einen Ortsnamen oder über die Gitterkoordinaten (nx, ny) abgerufen werden.

Dataset Registry

Dieses MCP besteht aus einer einzigen API (vier Operationen) und beinhaltet keine separate Daten­satz-Integration.

Bereitgestellte Tools

Installation und Deployment

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

Deployment auf fly.io:

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

Umgebungsvariablen

Regionsangabe

Geben Sie entweder area_name (z. B. „서울 중구“, „종로구 청운효자동“) oder die Gitterkoordinaten nx/ny an. Bei Verwendung von area_name erfolgt die automatische Zuordnung über die eingebaute Gitter-Zuordnungstabelle (3.838 Verwaltungsbezirke) in folgender Reihenfolge: 3. Ebene (읍면동) → 2. Ebene (시군구) → 1. Ebene (시도).

Rate Limit

Aufgrund des öffentlichen Serverbetriebs gelten die folgenden dreistufigen Begrenzungen:

• Mehr als 3 Anfragen pro Minute → 429

• 5 Verstöße innerhalb einer Stunde → 24 Stunden Sperrung

• Mehr als 30 pro Tag → 429

In der fly.io-Multimachine-Umgebung (2 Maschinen) können die Rate-Limit-Zähler pro Maschine getrennt geführt werden. Dies wird als bekannter Trade-off akzeptiert (Verfügbarkeits­priorität).

In der Praxis bestätigte Feststellungen

• Das Standardwert von numOfRows bei get_vilage_fcst ist auf 1000 gesetzt (praktisch bestätigt anhand von Beispielantworten mit totalCount 742~944; mit Standardwert 10 werden Ergebnisse abgeschnitten).

• Fehlerantworten bei dataType=JSON kommen tatsächlich im JSON-Format (bei ungültigen nx/ny-Anfragen wird ein JSON mit resultCode: "10" korrekt empfangen). Für den Fall der Hintergrund ist zusätzlich ein Regex-Fallback für die XML-Felder <resultCode>/<resultMsg> implementiert.

• Wird bei getFcst" eine ungültige base_time(z. B. 03:00) übergeben, wird der FehlerresultCode: "03"` (NO_DATA) zurückgegeben. Dies ist ein expliziter Fehler, keine leere Antwort.

• Für den Kurzzeitvorhersagebereich ab dem +4-Tages-Zeitraum (verlängerter Zeitraum) liefern PCP/SNO/WSD qualitative Codes (1=wenig, 2=normal, 3=viel), wie praktisch bestätigt wurde. Der Server wendet diese Codetabelle an, wenn fcstDate gegenüber baseDate um +4 Tage oder mehr getrennt ist, und markiert die Antwort mit is_extended_period: true.

• Es wurde bestätigt, dass get_fcst_version korrekt funktioniert, wenn basedatetime im selben YYYYMMDDHHmm-Format wie base_time übergeben wird (getestet mit ftype=SHRT).

Lizenz

MIT

Referenzen

• Originale API-Spezifikation: Kur iOS

• Original-API-Spezifikation: „OpenAPI-Nutzungsleitfaden für den Kurzfristvorhersage-Abrufdienst (2.0)“ der Korea Meteorological Administration

• Gitter-Längen-/Breitengrad-Zuordnungstabelle: Excel-Daten der KMA (Stand: Juli 2026, 3.838 Verwaltungsbezirke)

• Es wird ausschließlich das Gebiet Südkoreas unterstützt (Nordkoreaund Ausland nicht verfügbar).