weather-forecast-mcp

Предоставляет службу краткосрочного прогноза Корейского метеорологического управления (VilageFcstInfoService_2.0) в виде MCP-сервера (Model Context Protocol). Можно выполнять запросы к четырём операциям — сверхкраткосрочные данные текущей погоды, сверхкраткосрочный прогноз, краткосрочный прогноз и версия прогноза — по названию региона или координатам сетки (nx, ny).

Dataset Registry

Этот MCP состоит из одного API (4 операции), отдельного объединения наборов данных нет.

Предоставляемые инструменты

Установка и развертывание

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

Развертывание на fly.io:

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

Переменные окружения

Способ указания региона

Введите либо area_name (например, «서울 중구», «종로구 청운효자동»), либо координаты сетки nx/ny. При использовании area_name автоматическое сопоставление происходит во встроенной таблице соответствия сеток (для 3838 административных округов) в порядке: 3-й уровень (ып/мён/дон) → 2-й уровень (си/гун/гу) → 1-й уровень (си/до).

Rate Limit

Из-за публичного характера сервера применяются следующие трёхуровневые ограничения:

• более 3 запросов в минуту → 429

• 5 нарушений в течение 1 часа → блокировка на 24 часа

• более 30 запросов в сутки → 429

То, что в среде fly.io с несколькими машинами (2 шт.) счётчик rate limit может разделяться между машинами, является известным компромиссом и допускается (приоритет отдаётся доступности).

Проверенные на практике примечания

• Для get_vilage_fcst значение по умолчанию numOfRows установлено на 1000 (пример ответа показывает totalCount 742~944; при значении по умолчанию 10 данные обрезаются).

• При dataType=JSON ответ об ошибке действительно приходит в JSON (при некорректном запросе nx/ny подтверждено получение корректного JSON с resultCode: "10"). Дополнительно для подстраховки реализован резервный вариант с регулярным выражением для XML <resultCode>/<resultMsg>.

• Если для get_vilage_fcst указан недействительный base\_time (например, 03:00), возвращается ошибка resultCode: "03" (NO_DATA) — явная ошибка, а не пустой ответ.

• Подтверждено на практике, что в краткосрочном прогнозе +4 дня и позже (продлённый период) PCP/SNO/WSD возвращаются в виде качественных кодов (1=мало / 2=нормально / 3=много). Сервер применяет эту таблицу кодов, если fcstDate на 4 или более дней позже baseDate, и указывает в ответе is_extended_period: true.

• get_fcst_version корректно работает, если передать basedatetime в том же формате YYYYMMDDHHmm, что и base_time (по условию ftype=SHRT).

Лицензия

MIT

Ссылки

• Спецификация исходного API: руководство по использованию Open API службы краткосрочных прогнозов (2.0) Корейского метеорологического управления.

• Таблица соответствия сетки и координат: данные Excel, предоставленные КМА (по состоянию на июль 2026 года, 3838 административных округов).

• Доступен только Южнй Корё (рён Северью и зарубежью не предоставляется).