⚠️ 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-realtime-mcp

Es un servidor MCP que consulta la información de contaminación atmosférica en tiempo real, el Índice Integrado de Calidad del Aire (CAI) y la información de estaciones de medición de la API abierta AirKorea de la Corporación Ambiental de Corea.

Herramientas proporcionadas (5)

Related MCP server: seoul-air-quality-mcp

Fuente de datos

• Organismo proveedor: Departamento de Apoyo a Políticas de Calidad del Aire, División de Gestión de la Calidad del Aire, Oficina de Clima y Calidad del Aire, Corporación Ambiental de Corea

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

• Grupo de servicios: Servicios de consulta de información de contaminación atmosférica AirKorea de la Corporación Ambiental de Corea, información de estaciones de medición AirKorea de la Corporación Ambiental de Corea, e Índice Integrado de Calidad del Aire (CAI) de la Corporación Ambiental de Corea (código de grupo de servicios 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))

Unidades de medición y criterios de clasificación

Valores de clasificación (Grade): 1=bueno, 2=normal, 3=malo, 4=muy malo

Limitaciones conocidas (aspectos confirmados mediante mediciones reales)

• Ejes de coordenadas de la lista de estaciones (search_stations): al llamar fijado con ver=1.1, se confirma que dmX=longitud y dmY=latitud (verificación cruzada completada con 5 estaciones diferentes). Basado en WGS84.

• Sistema de coordenadas de consulta de estaciones cercanas (get_nearby_stations): se confirmó mediante mediciones reales que si se introducen las coordenadas WGS84 tal cual, se obtienen resultados completamente erróneos (por ejemplo, al introducir coordenadas del distrito de Gangnam en Seúl, se devuelven estaciones de la isla de Jeju). Es imprescindible la conversión de coordenadas al meridiano central TM (EPSG:5181), y este servidor llama a la API tras convertir automáticamente WGS84→EPSG:5181 con pyproj (el usuario solo necesita introducir latitud y longitud). Al introducir las coordenadas de la oficina del distrito de Gangnam (37.515336, 127.049357), la estación de Gangnam se devuelve en primer lugar con una distancia de 0.4 km, lo que verifica la precisión de la conversión.

• Campos de respuesta de la consulta CAI (get_station_cai): a diferencia de la tabla de la especificación (khaiValue/khaiGrade/khaiItem), los nombres reales de los campos son caiValue/caiGrade/caiItem. Los campos completos son stationCode, stationName, mangName, dataTime, caiValue, caiGrade, caiItem (los campos de contaminantes individuales como so2Value no se incluyen en la respuesta de esta operación).

• resultCode normal de la consulta CAI: las otras 4 operaciones devuelven resultCode="00" cuando son normales, pero solo getMsrstnKhaiRltmDnsty (CAI) responde con resultCode="200" y resultMsg="NORMAL_CODE" cuando es normal. El código del servidor está configurado para tratar también como normal los casos en que resultMsg es "NORMAL_CODE"/"NORMAL SERVICE".

• Diferencia en la estructura de respuesta de items: ArpltnInforInqireSvc/MsrstnInfoInqireSvc tienen items como array, mientras que RltmKhaiInfoSvc (CAI) está envuelto un nivel más con items.item. El servidor absorbe esta diferencia y siempre devuelve un array.

• Representación de valores faltantes: en el alcance de esta medición real (datos de calidad del aire normales) no aparecieron casos de valores faltantes "-", pero basándose en los ejemplos de la especificación, _safe_numeric está implementado para convertir de forma segura "-"/None/cadenas vacías/números flotantes (float) todos a None (no se sustituye arbitrariamente por 0).

• Estabilidad del servidor API: se confirmó que durante las mediciones reales se producía con frecuencia SERVICETIMEOUT_ERROR (código de error 05, HTTP 504). El servidor reintenta automáticamente hasta 3 veces solo para el código 05.

• sidoName "전남광주": se consulta correctamente (refleja el establecimiento de la Ciudad Especial de Jeonnam-Gwangju en 2026, se confirmaron 64 registros en totalCount).

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 con el conector de Claude.ai

Tras completar el despliegue, conéctese añadiendo /mcp al final de la dirección.

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

Política de límite de velocidad

Dado que es un servidor público al que se puede conectar solo con la URL sin clave API, se aplica un límite de velocidad de 3 niveles basado en IP.

• Más de 3 solicitudes por minuto: 429 (en despliegues de múltiples máquinas, puede aliviarse efectivamente en proporción al número de máquinas)

• Si se reciben 5 o más respuestas 429 dentro de 1 hora: bloqueo de 24 horas

• Más de 30 solicitudes en total por día (ventana móvil de 24 horas): 429

Códigos de error

Esta API utiliza el sistema estándar de códigos de error del Portal de Datos Públicos (diferente del sistema INFO-000/ERROR-3xx del Open Data Plaza de Seúl).

Proyectos relacionados

La API abierta 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)