⚠️ Aviso de cese del servicio Este servidor MCP finalizó su despliegue en fly.io el 2026-08-23. El código se conserva en el repositorio como referencia de desarrollo.

airkorea-statistics-mcp

Proporciona la API abierta Servicio de Estadísticas de Contaminación del Aire (ArpltnStatsSvc) de AirKorea, de la Corporación Ambiental de Corea, como un servidor MCP (Model Context Protocol) que Claude puede utilizar. Permite consultar información promedio en tiempo real por provincia/ciudad, condado y distrito, así como estadísticas diarias y mensuales por estación de medición.

Es la última fase del desarrollo en tres etapas de AirKorea y se concibe para usarse junto con la 1.ª fase (airkorea-realtime-mcp) y la 2.ª fase (airkorea-forecast-alert-mcp).

Funciones proporcionadas

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

Related MCP server: seoul-timeavg-air-mcp

Sobre el alcance de este MCP (importante)

Incluye únicamente 4 operaciones pertenecientes al Servicio de Estadísticas de Contaminación del Aire (ArpltnStatsSvc). Las siguientes 2 operaciones eran originalmente candidatas 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 la justificación y DEVLOG.md para el historial de la decisión):

• getTMStdrCrdnt (consulta de coordenadas de referencia TM) — pertenece al Servicio de Consulta de Información de Estaciones de Medición (MsrstnInfoInqireSvc), mismo grupo de servicios que la 1.ª fase (airkorea-realtime-mcp)

• getUnityAirEnvrnIdexSnstiveAboveMsrstnList (consulta de lista de estaciones de medición con índice integrado de calidad del aire ambiental en nivel "malo" o superior) — pertenece al Servicio de Consulta de Información de Contaminación del Aire (ArpltnInforInqireSvc), mismo grupo de servicios que las fases 1.ª y 2.ª

Si se añadirán o no estas dos operaciones a los repositorios de las fases 1.ª y 2.ª se decidirá por separado (estado pendiente).

Instalación y ejecución

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

Variables de entorno

Aviso: para invocar este MCP, es necesario haber solicitado por separado la autorización de uso del Servicio de Estadísticas de Contaminación del Aire (ArpltnStatsSvc) en el Portal de Datos Públicos (se requiere solicitud de uso individual por ID de servicio). Tras la solicitud, la aplicación efectiva tarda entre 1 y 2 horas.

Despliegue (fly.io)

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

Dirección de conexión del conector tras el despliegue:

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

Límite de tasa

Al ser un servidor público accesible sin autenticación, se aplica un límite de tasa en 3 niveles basado en IP:

• Más de 3 solicitudes por minuto: 429

• 5 infracciones en 1 hora: bloqueo de 24 horas

• Más de 30 solicitudes diarias (ventana móvil de 24 h): 429

En despliegues con múltiples máquinas, los contadores en memoria se separan por máquina, por lo que el límite efectivo puede relajarse proporcionalmente al número de máquinas.

Limitaciones conocidas (verificadas con mediciones reales, 2026-08-23)

• Los campos numéricos llegan como cadenas JSON y se convierten de forma segura a float en el código. Se ha confirmado que el valor faltante no es "-" sino cadena vacía ("") (observado en khaiValue, pm10Value, etc.).

• Se ha confirmado que la respuesta de getCtprvnMesureSidoLIst incluye realmente el campo khaiValue.

• Si se pasa sidoName=광주 o 전남 por separado, se devuelve totalCount=0 (sin datos) — para estas dos regiones es obligatorio consultar con el valor combinado 전남광주 para obtener datos correctos (comportamiento real distinto de la especificación).

• Las respuestas de error se devuelven correctamente en JSON dentro del rango medido (códigos 30, 10). El analizador de respaldo XML está implementado, pero no se ha podido reproducir una respuesta de error XML real — si en el futuro se encuentra un caso que llegue en XML, se registrará adicionalmente en DEVLOG.md.

• SERVICETIMEOUT (504) no se ha reproducido en pruebas locales — la lógica de reintento (máximo 3 veces) está implementada, pero su comportamiento en situaciones reales de tiempo de espera no se ha confirmado.

Fuente de datos

• Organismo proveedor: Corporación Ambiental de Corea (organismo subcontratado por el Ministerio de Medio Ambiente)

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

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

• Licencia: 공공누리 Tipo 1 (Atribución-Sin obras derivadas)

Licencia

Licencia MIT (para el código en sí). Los datos originales siguen la licencia 공공누리 mencionada anteriormente.