airkorea-statistics-mcp

La API del servicio de estadísticas de contaminación del aire (ArpltnStatsSvc) de Air Korea, de la Corporación Ambiental de Corea, se ofrece como un servidor MCP (Model Context Protocol) que Claude puede utilizar. Se pueden consultar los promedios en tiempo real por provincia (sido) y por municipio (sigungu), así como las estadísticas de promedio diario y mensual de cada estación de medición.

Es la última fase del desarrollo separado de Air Korea en tres fases, y se utiliza de forma prevista junto con la 1.ª fase (airkorea-realtime-mcp) y la 2ª fase (airkorea-forecast-alert-mcp).

Funciones

Unidades de medida: SO2/CO/O3/NO2 = ppm, PM10/PM2.5 = ㎍/㎥

Acerca del alcance de este MCP (importante)

Solo se incluyen las 4 operaciones del servicio de gestión de la calidad del aire (ArpltnStatsSvc). Las 2 operaciones siguientes eran candidatas en un principio para la 3ª fase, pero en realidad pertenecen a otros grupos de servicios y se han excluido de este alcance (consulte la sección 0-1 de DEVPLAN.md para ver la justificación y DEVLOG.md para la decisión):

• getTMStdrA (consulta de coordenadas de referencia TM) — pertenece al servicio de consulta de información de estaciones de medición (MsrstnInfoInqireSvc), el mismo grupo de servicios que la 1ª fase (airkorea-realtime-mcp)

• getUnityAirEnvrnIdxSnestiveAboveMsrstnList (consulta de estaciones de medición con índice de calidad del aire integrado "malo" o superior) — pertenece al servicio de consulta de información de contaminación del aire (ArpltnInforInqrSvc), el mismo grupo de servicios que la 1ª y 2ª fase

La decisión de añadir estas dos operaciones a los repositorios de la 1ª y 2ª fase se discutirá en el futuro (pendiente).

Instalación y ejecución

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

Variables de entorno

Nota: Para poder invocar este MCP, es necesario que el servicio de estadísticas de contaminación del aire (ArpltnStatsSvc) se haya solicitado de forma separada para su uso (se debe solicitar por cada ID de servicio). Después de la solicitud, la aplicación tarda de 1 a 2 horas en aplicarse.

Implementación (fly.io)

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

Dirección de conexión del conector después de la implementación:

https://airkorea-statistics-mcp.fly.dev/mcp

Límite de peticiones

Dado que es un servidor público accesible sin autenticación, se aplica un límite de peticiones en 3 niveles según la IP:

• 429 si se superan las 3 peticiones por minuto

• Bloqueo de 24 horas si se producen 5 infracciones dentro de 1 hora

• 429 si se superan las 30 peticiones en total por día (rolling 24h)

En implementaciones multiproceso, los contadores en la memoria se separan por máquina, por lo que el límite real puede verse reducido de forma proporcional al número de máquinas.

Limitaciones conocidas (confirmadas mediante medición real, 2026-08-23)

• Los campos numéricos vienen como cadenas JSON y se convierten de forma segura a float en el código; la representación de los valores omitidos se confirma como cadena vacía (""), no "-" (observado en khaiValue, pm10Value).

• Se confirma que la respuesta de getCtprvnMesureSidoLIst contiene de hecho el campo khaiValue.

• Si se pasa sidoName=광주 o 전남 de forma aislada, se devuelve totalCount=0 (sin datos): para estas dos regiones se debe consultar con el valor combinado 전남광주 para que lleguen los datos normales (comportamiento real distinto del especificado).

• Las respuestas de error se devuelven como JSON normal en el rango de datos reales verificado (códigos 30, 10). El parseador de fallback XML está implementado, pero no se ha podido reproducir una respuesta de error real en XML; si en el futuro se encuentra un caso que llegue en XML, se dejará constancia añadida en DEVLOG.md.

• SERVICETIMEOUT(504) no se ha podido reproducir en las pruebas locales; la lógica de reintento (máximo 3 veces) está implementada, pero no se ha verificado su funcionamiento en una situación real de timeout.

Fuente de los datos

• Organismo que lo proporciona: Korea Environment Corporation (una organización encargada por el Ministerio de Medio Ambiente)

• Plataforma: Portal de datos abiertos (data.go.kr)

• Nombre de la API: 공기환경공단_에어코리아_대기오염통계 현황 (ArpltnStatsSvc)

• Licencia: KOGL tipo 1 (Atribución de la Fuente - Prohibido modificar)

Licencia

Licencia MIT (del código en sí). Los datos originales se rigen por la misma licencia de arriba.