seoul-timeavg-air-mcp

Servidor MCP (Model Context Protocol) para consultar información del promedio por hora del aire ambiente en Seúl por período. Proporciona datos de promedio por hora de PM10, PM2.5, ozono, dióxido de nitrógeno, monóxido de carbono y dióxido de azufre por estación de medición/área.

Fuente de datos

• Entidad proveedora: Departamento de Política del Aire de la Oficina de Clima y Medio Ambiente de la Ciudad de Seúl

• Plataforma: Plataforma de Datos Abiertos de Seúl — ID de servicio: OA-221, Nombre del servicio: Información del promedio por hora del aire ambiente en Seúl por período (TimeAverageCityAir)

• Alcance de la licencia de uso: Tipo 1 de Open Government License (Atribución, uso comercial y modificación permitidos)

Herramientas proporcionadas (Tools)

get_time_average_air

Consulta la información de la calidad del aire promedio por hora en la fecha y hora de medición especificada (YYYYMMDDHHmm).

• msrmt_dt (obligatorio): fecha y hora de medición, formato de 12 dígitos YYYYMMDDHHmm, los minutos (mm) siempre son 00 (ejemplo: 202401011200). No se consulta con 10 dígitos (YYYYMMDDHH) de resultados reales.

• start_index (opcional, por defecto 1): posición de inicio de la consulta

• end_index (opcional, por defecto 25): posición de fin de la consulta (máximo 1000 registros a la vez)

• sarea_nm (opcional): nombre del área (ejemplo: 도심권, 서북권)

• msrstn_nm (opcional): nombre de la estación (ejemplo: 종로구, 용산구)

Campos devueltos: fecha y hora de medición, código/nombre del área, código/nombre de la estación, PM10 1 hora (㎍/㎥), PM10 24 horas (㎍/㎥), PM2.5 (㎍/㎥), Ozono (ppm), Dióxido de nitrógeno (ppm), Monóxido de carbono (ppm), Dióxido de azufre (ppm)

search_stations

Busca datos de calidad del aire en un momento específico por nombre de estación o nombre de área.

• msrmt_dt (obligatorio)

• sarea_nm (opcional)

• msrstn_nm (opcional)

Instalación y ejecución local

git clone https://github.com/hlucent/seoul-timeavg-air-mcp.git
cd seoul-timeavg-air-mcp
pip install -r requirements.txt
cp .env.example .env
# .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

Dirección de conexión del conector de Claude.ai después del despliegue:

https://seoul-timeavg-air-mcp.fly.dev/mcp

Limitaciones conocidas

• La clave de autenticación se pasa como segmento de ruta URL, no como parámetro de consulta (http://openAPI.seoul.go.kr:8088/{KEY}/{TYPE}/TimeAverageCityAir/...).

• El número máximo de registros que se pueden consultar a la vez es 1000 (END_INDEX - START_INDEX ≤ 1000, de lo contrario ERROR-336). Al usar la clave de muestra (sample), el máximo es 5 registros (ERROR-335).

• MSRMT_DT solo se consulta correctamente en 12 dígitos (YYYYMMDDHHmm, minutos siempre 00). Con 10 dígitos se devuelve INFO-200 (sin datos).

• Resultados observados de la combinación de parámetros opcionales (nombre de área/nombre de estación):

  • Ambos omitidos: devuelve todo

  • Solo especificar sarea_nm: filtra correctamente por esa área

  • Solo especificar msrstn_nm (omitir área): se ha observado un comportamiento anómalo de la API donde el filtro se ignora y se devuelve todo. Este servidor detecta este caso y vuelve a filtrar la respuesta por nombre de estación.

  • Ambos especificados: filtra correctamente (intersección)

• No se admite HTTPS (falla la conexión). Solo se usa HTTP (puerto 8088).

• Algunas respuestas de error (por ejemplo, ERROR-335, ERROR-336) se devuelven en XML incluso para solicitudes TYPE=json. Este servidor intenta analizar JSON primero y, si falla, recurre a XML.

• Este servidor permite que cualquiera se conecte como conector sin clave API, por lo que se aplica un límite de tasa basado en IP (3 solicitudes por minuto, bloqueo de 24 horas si se reciben 5 o más errores 429 en 1 hora, límite diario de 30 solicitudes).

Licencia

• Código: Licencia MIT

• Datos: Tipo 1 de Open Government License (Atribución, Ciudad de Seúl)