seoul-realtime-air-by-region-mcp

Servidor MCP para consultar el estado en tiempo real de la calidad del aire por región (zona céntrica/noreste/sureste/noroeste/suroeste) de Seúl. Está basado en la API RealtimeCityAir de la Plataforma de Datos Abiertos de Seúl.

• Institución/Depart: Departamento de Políticas de Calidad del Aire, Dirección de Medio Ambiente Climático, Gobierno Metropolitano de Seúl

• Datos originales: Plataforma de Datos Abiertos de Seúl — Estado en tiempo real de la calidad del aire por región de Seúl

• Licencia (datos): Tipo 1 de Gonggongnuri (Atribución, uso comercial y modificación permitidos)

• Licencia (código): MIT

Herramientas proporcionadas

get_realtime_air_by_region

Consulta el estado en tiempo real de la calidad del aire por región (o una región/estación de monitoreo específica).

Campos de respuesta: Fecha de medición (MSRMT_DT), Región (SAREA_NM), Estación de monitoreo (MSRSTN_NM), PM10 (PM, ㎍/㎥), PM2.5 (FPM, ㎍/㎥), Ozono (OZON, ppm), Dióxido de nitrógeno (NTDX, ppm), Monóxido de carbono (CBMX, ppm), Dióxido de azufre (SPDX, ppm), Grado de calidad del aire integrado (CAI_GRD), Índice de calidad del aire integrado (CAI_IDX), Sustancia determinante del índice (CRST_SBSTN)

list_available_regions

Devuelve una lista fija de los 5 nombres de región consultables (zona céntrica/noreste/sureste/noroeste/suroeste). No requiere llamada a la API.

Related MCP server: mcp-waqi

Restricciones confirmadas mediante pruebas reales

• La clave de autenticación se pasa como segmento de la ruta URL (/{KEY}/json/RealtimeCityAir/...), no como parámetro de consulta.

• msrstn_nm no se puede usar solo sin sarea_nm. Debido a la estructura de la ruta de la API, los parámetros opcionales están fijos en el orden: posición SAREA_NM → posición MSRSTN_NM. Si se omite sarea_nm y solo se pasa msrstn_nm, ese valor se interpreta en la posición SAREA_NM, devolviendo INFO-200 (sin datos). Este servidor filtra las solicitudes que especifican solo msrstn_nm antes de llamar a la API, mostrando un error claro.

• Si se amplía el rango de start_index/end_index, se devuelven correctamente varios registros (se confirman 25 registros en una consulta completa).

• Las respuestas normales son JSON, pero algunas respuestas de error (como error de clave de autenticación INFO-100) se devuelven en XML incluso cuando la solicitud es de tipo TYPE=json. Este servidor utiliza un analizador de respaldo que extrae <CODE>/<MESSAGE> del XML si falla el análisis JSON.

• Se ha confirmado que el valor de CAI_GRD (Grado de calidad del aire integrado) es "Bueno" o "Normal" en el momento de la medición ("Malo"/"Muy malo" no se observaron en el momento de la prueba, pero existen según la especificación).

Instalación y ejecución (local)

git clone https://github.com/hlucent/seoul-realtime-air-by-region-mcp.git
cd seoul-realtime-air-by-region-mcp
pip install -r requirements.txt
cp .env.example .env  # SEOUL_API_KEY 값 입력
python server.py

Variables de entorno

Despliegue (fly.io)

fly launch --no-deploy
fly secrets set SEOUL_API_KEY=<발급받은키>
flyctl deploy

Al conectar el conector de Claude.ai después del despliegue, regístrelo agregando la ruta /mcp de la siguiente manera:

https://<앱이름>.fly.dev/mcp

Seguridad

Este servidor está expuesto públicamente sin clave de autenticación y tiene un límite de tasa de 3 niveles basado en IP (3 veces por minuto — en implementaciones multimáquina, puede aliviarse proporcionalmente al número de máquinas; 5 infracciones por hora resultan en un bloqueo de 24 horas; límite total diario de 30 veces).

La IP se determina prioritariamente mediante el encabezado Fly-Client-IP (establecido directamente por el edge de fly.io, no falsificable por el cliente). El contador del límite de tasa se mantiene en memoria (dict) por proceso y no se comparte entre máquinas. Por lo tanto, si fly.io distribuye las solicitudes entre varias máquinas, el límite real para una misma IP puede aliviarse a "3 veces por minuto × número de máquinas en ejecución". Esta es una compensación de diseño por implementar el límite de tasa en memoria sin almacenamiento externo.

Licencia

Licencia MIT. Los datos originales siguen el Tipo 1 de Gonggongnuri.