airkorea-realtime-mcp

Servidor MCP para consultar información de contaminación del aire en tiempo real · Índice Integrado de Calidad del Aire (CAI) · 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: mcp-waqi

Fuente de datos

• Proveedor: Departamento de Política de Calidad del Aire, División de 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 del aire de AirKorea de la Corporación Ambiental de Corea, información de estaciones de medición de AirKorea de la Corporación Ambiental de Corea, servicios de consulta del Índice Integrado de Calidad del Aire (CAI) de AirKorea de la Corporación Ambiental de Corea (código de grupo de servicios B552584)

• Licencia de uso: Atribución-NoDerivadas (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 calificación

Valores de calificación (Grado): 1=Bueno, 2=Moderado, 3=Malo, 4=Muy malo

Limitaciones conocidas (confirmadas mediante medición real)

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

• Sistema de coordenadas de consulta de estaciones cercanas (get_nearby_stations): Si se ingresan latitud/longitud WGS84 directamente, se obtienen resultados completamente erróneos (por ejemplo, al ingresar coordenadas de Gangnam, Seúl, devuelve estaciones de Jeju). Se confirma mediante medición real que es imprescindible la conversión de coordenadas a TM Origen Central (EPSG:5181); este servidor convierte automáticamente WGS84→EPSG:5181 con pyproj antes de llamar a la API (el usuario solo necesita ingresar latitud/longitud). Al ingresar las coordenadas de la Oficina de Gangnam (37.515336, 127.049357), la estación de Gangnam aparece como la más cercana con una distancia de 0.4 km, lo que verifica la precisión de la conversión.

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

• resultCode normal de consulta CAI: Mientras que las otras 4 operaciones devuelven resultCode="00" en caso normal, getMsrstnKhaiRltmDnsty(CAI) responde con resultCode="200", resultMsg="NORMAL_CODE". El código del servidor también trata resultMsg "NORMAL_CODE"/"NORMAL SERVICE" como estado normal.

• Diferencia en la estructura de respuesta de items: ArpltnInforInqireSvc/MsrstnInfoInqireSvc tienen items como arreglo, mientras que RltmKhaiInfoSvc(CAI) tiene un nivel adicional de encapsulamiento con items.item. El servidor absorbe esta diferencia y siempre devuelve un arreglo.

• Expresión de valores faltantes: En este rango de medición real (datos normales de calidad del aire) no aparecieron casos faltantes con "-", pero basándose en los ejemplos de la especificación, _safe_numeric está implementado para convertir de forma segura "-"/None/cadena vacía/flotante a None (no se reemplaza con 0 arbitrariamente).

• Estabilidad del servidor de API: Se confirmó mediante medición real que SERVICETIMEOUT_ERROR (código de error 05, HTTP 504) ocurre con frecuencia. El servidor reintenta automáticamente hasta 3 veces solo para el código 05.

• sidoName "전남광주": Se consulta correctamente (refleja el establecimiento de la Ciudad Metropolitana Especial de Jeonnam-Gwangju en 2026, confirmado con 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

Después de completar el despliegue, conéctese agregando /mcp al final de la dirección.

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

Política de límite de velocidad

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

• Si se superan 3 solicitudes por minuto: 429 (en despliegue multi-máquina, el límite efectivo puede aliviarse proporcionalmente al número de máquinas)

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

• Si se superan 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 de la Plataforma Abierta de Datos de Seúl).

Proyectos relacionados

La API abierta AirKorea es de gran escala y 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 datos (Ministerio de Medio Ambiente/Corporación Ambiental de Corea)