airkorea-forecast-alert-mcp

Servidor MCP que consulta la serie de predicción de calidad del aire, alertas de material particulado fino y avisos de ozono/tormenta de arena de la OpenAPI de AirKorea de la Corporación Ambiental de Corea (Korea Environment Corporation).

Herramientas proporcionadas

Nota de diseño: En la sección 3 de DEVPLAN.md se indicó revisar primero la opción de agrupar los avisos de ozono y de tormenta de arena en una sola herramienta (con bifurcación mediante el parámetro advisory_type), pero tras la verificación real se determinó que, dado que los campos de respuesta de las dos operaciones difieren considerablemente (el ozono tiene 8 campos como concentración y nivel de emisión, mientras que la tormenta de arena tiene solo 2 campos de texto: número de ciclo y región), agruparlos en una sola herramienta degradaría la usabilidad, por lo que se separaron en 2 herramientas (6 herramientas en total).

Related MCP server: korean-public-data-mcp

Fuente de datos

• Organización proveedora: Departamento de Apoyo a Políticas de Calidad del Aire, División de Gestión Ambiental Atmosférica, Centro de Clima y Atmósfera, Corporación Ambiental de Corea

• Plataforma: Portal de Datos Públicos (data.go.kr)

• Grupo de servicios: Corporación Ambiental de Corea_AirKorea_Información de Contaminación del Aire (parcial), Corporación Ambiental de Corea_AirKorea_Información de predicción de PM2.5 de alta concentración (superior a 50), Corporación Ambiental de Corea_AirKorea_Estado de emisión de alertas de material particulado, Corporación Ambiental de Corea_AirKorea_Información de ocurrencia de ozono y tormenta de arena (código de grupo de servicio B552584)

• Alcance de la licencia de uso: Atribución-SinDerivadas (obligación de indicar la fuente de los datos (Ministerio de Medio Ambiente/Corporación Ambiental de Corea))

Ciclo de publicación (importante)

Limitaciones conocidas (aspectos confirmados mediante verificación real, por operación — verificación real del 22/23-08-2026)

get_air_quality_forecast (getMinuDustFrcstDspth)

• Confirmada la existencia real del campo informData. Cada elemento del array de items distingue la predicción de hoy/mañana/pasado mañana, y el valor de informData (AAAA-MM-DD) indica la fecha objetivo de dicha predicción. (Ej.: cuando dataTime es "publicado a las 23:00 del 22-08-2026", los items llegan en el orden informData "2026-08-22"/"2026-08-23"/"2026-08-24")

• Al consultar fuera de temporada de ozono (O3) (noviembre a marzo), se recibe una lista vacía sin errores (resultCode: "00", totalCount: 0) (confirmado mediante verificación real el 15-01-2026).

• El parámetro ver=1.1 no se utilizó en esta verificación real (se confirmó que el método básico/versión anterior funciona suficientemente). Las URL de imágenes (imageUrl1~imageUrl9) se devuelven tal cual como enlaces de referencia.

get_high_pm25_forecast (getMinuDustFrcstDspth50Over)

• Como la especificación no incluye tabla de especificaciones (solo se indica como referencia al documento SWAGGER), todo se determinó mediante verificación real.

• Confirmado el funcionamiento normal de los parámetros searchDate e informCode (PM10/PM25/O3).

• Lista completa de nombres de campos {región}50Over de las 19 regiones (confirmado mediante verificación real, en orden alfabético): busan50Over, chungbuk50Over, chungnam50Over, daegu50Over, daejeon50Over, gwangju50Over, gyeongbuk50Over, gyeonggibuk50Over, gyeongginam50Over, gyeongnam50Over, incheon50Over, jeju50Over, jeonbuk50Over, jeonnam50Over, sejong50Over, seoul50Over, ulsan50Over, youngdong50Over, youngseo50Over (también se proporcionan los campos {región}Grade con el mismo patrón de nombre, con texto bueno/regular/malo/muy malo).

• ⚠️ Requiere verificación (pendiente): Se confirmó mediante verificación real que el valor en caso de no superación es "X", pero el valor en caso de superación (valor estimado "O" en el cuerpo de la especificación) no se ha podido confirmar porque no se reprodujo durante agosto de 2026 (período en el que PM2.5 es estacionalmente bajo). En el código se mantiene el valor estimado de la especificación ("O") como valor predeterminado, y se requiere una nueva verificación cuando ocurra una concentración alta real.

• Confirmado mediante verificación real que el período consultable está limitado a aproximadamente el último mes (si se consulta con un searchDate anterior, se obtiene una lista vacía con totalCount: 0).

get_pm_alarm_status (getUlfptcaAlarmInfo)

• Según la especificación, para las alertas aún no levantadas, clearDate llega como "--", clearTime como ":00" y clearVal como "공람" (no numérico). Esta herramienta, en ese caso, procesa dichos campos como null en la conversión segura y, además, indica explícitamente el estado "no levantada (en curso)" mediante los campos separados cleared (bool)/status (cadena).

• ⚠️ Requiere verificación (pendiente): Se consultaron todos los datos reales de 2025~2026 (448 casos en total), pero todos estaban ya levantados, y no se encontró ningún caso en el que se reprodujera realmente el patrón de no levantada ("--"/"공람"). Se requiere una nueva verificación cuando ocurra una alerta no levantada en el futuro.

get_ozone_advisory / get_yellowdust_advisory

• Los avisos de ozono tienen una estacionalidad que se publican solo de abril a octubre de cada año (los datos fuera de temporada simplemente no existen; además, en la verificación real de O3 fuera de temporada de get_air_quality_forecast mencionada anteriormente, se confirmó por separado que la API en sí funciona correctamente).

• Tanto get_ozone_advisory como get_yellowdust_advisory confirmaron llamadas correctas mediante verificación real con el parámetro year (2026/2025).

Común: inestabilidad intermitente de la propia API del Portal de Datos Públicos

• Durante la verificación real, en las llamadas a getMinuDustFrcstDspth, getMinuDustWeekFrcstDspth y getMinuDustFrcstDspth50Over se produjeron de forma intermitente SERVICETIMEOUT_ERROR (código 05) o timeouts de red puros. Al reintentar la misma solicitud, en la mayoría de los casos se recibió una respuesta normal — se considera un problema de carga del propio servidor del Portal de Datos Públicos, no un defecto del código. El cliente utiliza un timeout de 30 segundos de httpx, y se recomienda que el llamador reintente si es necesario.

Variables de entorno

Instalación y ejecución (local)

pip install -r requirements.txt --break-system-packages
cp .env.example .env   # AIRKOREA_SERVICE_KEY 값 입력
python server.py

Despliegue (fly.io)

fly launch --no-deploy
# fly.toml이 [http_service] 방식인지 확인 후
fly secrets set AIRKOREA_SERVICE_KEY=발급받은키
flyctl deploy

Conexión del conector de Claude.ai

https://airkorea-forecast-alert-mcp.fly.dev/mcp

Política de límite de velocidad

• 429 si se superan 3 solicitudes por minuto (en despliegues multimáquina, puede aliviarse de forma proporcional al número de máquinas)

• Bloqueo de 24 horas si se reciben 5 o más respuestas 429 en 1 hora

• 429 si se superan 30 solicitudes en total por día (ventana móvil de 24 horas)

Códigos de error

Se utiliza el sistema de códigos de error estándar del Portal de Datos Públicos (idéntico al de airkorea-realtime-mcp de la fase 1).

Proyectos relacionados

La OpenAPI de AirKorea es de gran escala, por lo que se desarrolla dividida en 3 MCP independientes:

Licencia

MIT (código) / Cumplimiento de la Licencia Pública de Corea Tipo 1 (Atribución) — indicación de la fuente de los datos (Ministerio de Medio Ambiente/Corporación Ambiental de Corea)