airquality-tr-mcp

Servidor MCP que proporciona datos oficiales de calidad del aire en tiempo real e históricos para Türkiye.

Documentación

airquality-tr-mcp

Presenta los datos oficiales de la Red Nacional de Monitoreo de Calidad del Aire (UHKİA) de Turquía como un servidor MCP (Model Context Protocol); un asistente compatible con MCP, como Claude Desktop, puede responder preguntas en tiempo real y retrospectivas sobre la calidad del aire para 81 provincias y más de 365 estaciones en Turquía.

Versión estable actual: v1.1.0

Esta es una integración no oficial. No tiene conexión con el Ministerio de Medio Ambiente, Urbanización y Cambio Climático de la República de Turquía y no cuenta con su respaldo. Es responsabilidad del usuario cumplir con los términos de uso del portal de origen.

Fuentes de datos

Mediciones de calidad del aire: UHKİA (sim.csb.gov.tr) — a través de endpoints oficiales, no documentados pero públicos. El servidor utiliza los valores de ICA (Índice de Calidad del Aire), categoría y contaminante dominante devueltos por la fuente tal como están; no realiza cálculos, promedios ni estimaciones propios.
Geocodificación: OpenStreetMap Nominatim (https://nominatim.openstreetmap.org/search) — se utiliza únicamente para convertir una ubicación dada como texto en latitud/longitud; no proporciona datos de calidad del aire y no requiere clave de API. La entrada de coordenadas no llama a este servicio en absoluto.

Requisitos

Python 3.11+
uv

Instalación

Desde PyPI (recomendado):

pip install airquality-tr-mcp
# veya
uvx airquality-tr-mcp

Instalación para desarrollo clonando el repositorio:

cd airquality-tr-mcp
uv sync

Configuración de Claude Desktop / Codex (stdio)

Si se instaló con el paquete PyPI:

{
  "mcpServers": {
    "airquality-tr": {
      "command": "uvx",
      "args": ["airquality-tr-mcp"]
    }
  }
}

Con instalación de desarrollo clonada desde el repositorio:

{
  "mcpServers": {
    "airquality-tr": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/airquality-tr-mcp",
        "run",
        "python",
        "-m",
        "airquality_tr_mcp.server"
      ]
    }
  }
}

Ejecución como API REST

También hay una API REST independiente que utiliza la misma lógica de negocio que el servidor MCP:

uv run airquality-tr-api
# veya
uv run uvicorn airquality_tr_mcp.api:app --reload

Por defecto escucha en http://localhost:8000. Visite http://localhost:8000/docs para documentación interactiva. Los endpoints se corresponden uno a uno con las herramientas MCP (/stations, /air-quality, /nearest-air-quality, /station, /historical-data, /trend-summary, /compare-cities, /ranking, /detailed-ranking, /health-advisory, /alert) y devuelven los mismos cuerpos JSON en turco; la única diferencia es que en casos de error (respuestas con el campo hata completo) se devuelve un código de estado HTTP apropiado (400/404/409/429/502/504).

Herramientas

Herramienta	Propósito
`ping`	Comprueba si el proceso MCP está activo
`list_stations`	Lista las estaciones UHKİA activas
`get_air_quality`	Resumen provincial y desglose por estación
`get_nearest_air_quality`	Datos de la estación oficial más cercana por texto o coordenadas
`get_station_detail`	Medición actual completa de una sola estación
`get_historical_data`	Resúmenes históricos diarios
`get_trend_summary`	Tendencia de 3/6 días basada en reglas
`compare_cities`	Comparación compacta entre dos provincias
`get_ranking`	Clasificación a nivel provincial
`get_detailed_ranking`	Clasificación nacional a nivel de estación
`get_health_advisory`	Recomendación de salud provincial basada en reglas
`check_alert`	Verificación de umbrales de ICA/contaminantes bajo demanda

get_air_quality y get_nearest_air_quality sirven para propósitos diferentes:

get_air_quality — proporciona el resumen de una provincia y el desglose de todas las estaciones en esa provincia; el valor representativo en el resumen provincial es la estación con el peor (ICA más alto) de esa provincia.
get_nearest_air_quality — encuentra la estación más cercana a una ubicación (texto o coordenadas) con una medición de ICA válida dentro del límite de referencia de 75 km; no le importan los límites provinciales.
get_health_advisory — genera una recomendación determinista basada en reglas según el estado representativo (peor estación) de una provincia.
get_ranking vs get_detailed_ranking — get_ranking proporciona una clasificación rápida con un único valor representativo por provincia; get_detailed_ranking clasifica los mismos datos a nivel de estación a nivel nacional, sin resumirlos por provincia.

Ejemplos de llamadas

ping()

list_stations()
list_stations(province="İstanbul")
list_stations(province="Kadıköy")

get_air_quality(province="Ankara")
get_air_quality(province="İstanbul", district="Kadıköy")

get_station_detail(station="Ankara - Çankaya")
get_station_detail(station="a1b2c3d4-e5f6-7890-abcd-ef1234567890")

get_historical_data(province="İzmir", days=7)
get_historical_data(province="İstanbul", days=14, district="Kadıköy")

get_trend_summary(province="Bursa", days=3)
get_trend_summary(province="Bursa", days=6)

compare_cities(province1="İstanbul", province2="Ankara")

get_ranking(mode="worst", limit=10)
get_ranking(mode="best", limit=5)

get_detailed_ranking(mode="worst", limit=20)

get_health_advisory(province="Kocaeli")

check_alert(province="İstanbul", threshold=100)
check_alert(province="Ankara", threshold=50, pollutant="PM10")
check_alert(province="İzmir", threshold=40, pollutant="PM10", district="Konak")

Ejemplos de `get_nearest_air_quality`

get_nearest_air_quality(location="Göbeklitepe, Şanlıurfa")
get_nearest_air_quality(latitude=37.2232, longitude=38.9224)

Privacidad, atribución y limitaciones

Las consultas de ubicación por texto se envían a OpenStreetMap Nominatim; la entrada de coordenadas omite por completo esta transferencia.
Las mediciones de calidad del aire provienen de UHKİA.
La distancia es un cálculo local en línea recta (Haversine), no una distancia por carretera/ruta.
referans_hki no es una estimación, interpolación ni promedio local; es el valor oficial de la estación correspondiente en la fuente.
Una medición con más de dos horas de antigüedad se devuelve igualmente con una advertencia explícita.
Este paquete es un software stdio local; no hay un servicio centralizado/alojado en v1.
El parámetro location no tolera errores tipográficos de provincia/distrito tan bien como get_air_quality (Nominatim realiza búsqueda de texto libre, no corrección difusa de provincia/distrito); si solo se pregunta por la calidad del aire general de una provincia/distrito, se debe preferir get_air_quality/list_stations.
Nominatim/OpenStreetMap y UHKİA son dos servicios externos independientes y sin relación entre sí.

Licencia

Este proyecto está licenciado bajo la Licencia MIT.

airquality-tr-mcp

Documentación