weather-forecast-mcp

El servicio de consulta de pronósticos a corto plazo de la Administración Meteorológica de Corea (VilageFcstInfoService_2.0) se ofrece como servidor MCP (Model Context Protocol). Permite consultar las cuatro operaciones — observación a muy corto plazo, pronóstico a muy corto plazo, pronóstico a corto plazo y versión del pronóstico — mediante un nombre de región o las coordenadas de cuadrícula (nx, ny).

Dataset Registry

Este MCP se compone de una única API (4 tipos de operaciones) y no incluye integración adicional de conjuntos de datos.

Herramientas proporcionadas

Instalación y despliegue

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

Despliegue en fly.io:

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

Variables de entorno

Método de especificación de la región

Se introduce area_name(p. ej., "서울 중구", "종로구 청운효자동") o las coordenadas de cuadrícula nx/ny. Al usar area_name, se realiza una coincidencia automática en la tabla de mapeo de cuadrículas integradas (3.838 áreas administrativas) desde el nivel 3 (읍면동) hasta el nivel 1 (도) en el siguiente orden: nivel 3 → nivel 2 → nivel 1.

Rate Limit

Debido a la naturaleza del servidor público, se aplican las siguientes restricciones de 3 niveles:

• Más de 3 llamadas por minuto → 429

• 5 infracciones dentro de 1 hora → bloqueo de 24 horas

• Más de 30 llamadas al día → 429

En el entorno de fly.io con múltiples máquinas (2), el contador de límite de velocidad puede separarse por máquina; es una limitación conocida y se acepta como tradeoff (prioridad a la disponibilidad).

Comprobaciones realizadas en pruebas reales

• Los casos de get_vilage_fcst utilizan el error numOfRows con valor predeterminado 1000 (verifica en datos de ejemplo: totalCount 742~944; con el valor 10 se truncaría)

• Las respuestas de error con dataType=JSON llegan realmente en formato JSON (se confirma cuando se solicita con nx/ny no válidos, la respuesta incluye JSON con resultCode: "10"). No obstante, se implementó una alternativa de expresión regular para XML con <resultCode>/<resultMsg> por precaución

• Si se especifica un base_time no válido (p. ej., las 03:00) en get_vilage_fcst, se devuelve el error resultCode: "03" (NO_DATA), no una respuesta vacía

• Desde el día +4 del pronóstico a corto plazo (período extendido), la PCP/SNO/WSD llegan con códigos cualitativos (1=escaso/2=normal/3=abundante), lo cual se confirmó en pruebas reales. El servidor aplica la tabla de códigos cuando fcstDate es +4 días mayor que baseDate, e indica en la respuesta is_extended_period: true

• get_fcst_version se comporta correctamente cuando basedatetime se proporciona con el mismo formato YYYYMMDDHHmm que base_time (con base en ftype=SHRT)

Licencia

MIT

Referencias

• Especificación original de la API: guía de uso de la API abierta (2.0) del servicio de consulta de pronósticos a corto plazo de la Administración Meteorológica de Corea

• Tabla de mapeo de cuadrícula-longitud y latitud ~: datos Excel proporcionados por la Administración Meteorológica de Corea (con referencia a 3.838 áreas administrativas en julio de 2026)

• Solo se proporciona la región de Corea del Sur (no se ofrece Corea del Norte ni fuera del país)