airquality-tr-mcp

Türkiye'nin resmi Ulusal Hava Kalitesi İzleme Ağı (UHKİA) verisini bir MCP (Model Context Protocol) sunucusu olarak sunar; Claude Desktop gibi MCP-uyumlu bir asistan, Türkiye'deki 81 il ve 365+ istasyon için gerçek zamanlı ve geçmişe dönük hava kalitesi sorularını yanıtlayabilir.

Bu, resmi olmayan (unofficial) bir entegrasyondur.T.C. Çevre, Şehircilik ve İklim Değişikliği Bakanlığı ile bir bağlantısı yoktur ve onlar tarafından desteklenmemektedir. Kaynak portalın kullanım şartlarına uymak kullanıcının sorumluluğundadır.

- Hava kalitesi ölçümleri:UHKİA (sim.csb.gov.tr) — resmi, dokümante edilmemiş ama halka açık uç noktalar üzerinden. Sunucu, kaynağın döndürdüğü HKİ (Hava Kalitesi İndeksi), kategori ve baskın kirletici değerleriniolduğu gibikullanır; kendi hesaplaması, ortalaması veya tahmini yapılmaz.
- Konum çözümleme (geocoding):OpenStreetMap Nominatim (https://nominatim.openstreetmap.org/search) — yalnızca metinle verilen bir konumu enlem/boyluma çevirmek için kullanılır, hava kalitesi verisi sağlamaz, API anahtarı gerektirmez. Koordinat girişi bu servisi hiç çağırmaz.

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

Depoyu klonlayarak geliştirme amaçlı kurulum:

Claude Desktop / Codex yapılandırması (stdio)

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

Depodan klonlanmış geliştirme kurulumuyla:

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

MCP sunucusuyla aynı iş mantığını kullanan bağımsız bir REST API de mevcuttur:

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

Varsayılan olarakhttp://localhost:8000üzerinde dinler. Etkileşimli dokümantasyon içinhttp://localhost:8000/docsadresini ziyaret edin. Uç noktalar MCP tool'larıyla bire bir eşlenir (/stations,/air-quality,/nearest-air-quality,/station,/historical-data,/trend-summary,/compare-cities,/ranking,/detailed-ranking,/health-advisory,/alert) ve aynı Türkçe JSON gövdelerini döndürür; tek fark, hata durumlarında (hataalanı dolu yanıtlarda) uygun bir HTTP durum kodu (400/404/409/429/502/504) döndürülmesidir.

get_air_qualityveget_nearest_air_qualityfarklı amaçlara hizmet eder:

- get_air_quality— bir ilin özetini ve o ildekitümistasyonların dökümünü verir; il özetindeki temsili değer o ildeki en kötü (en yüksek HKİ'li) istasyondur.
- get_nearest_air_quality— bir konuma (metin veya koordinat)en yakınve 75 km referans sınırı içinde geçerli HKİ ölçümü olan istasyonu bulur; il sınırlarıyla ilgilenmez.
- get_health_advisory— bir ilin temsili (en kötü istasyon) durumuna göre kural tabanlı, deterministik tavsiye üretir.
- get_rankingvsget_detailed_ranking—get_rankingil başına tek temsili değerle hızlı bir sıralama verir;get_detailed_rankingaynı veriyi il bazında özetlemeden, istasyon seviyesinde ülke geneli sıralar.

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")

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

- Metinle konum sorguları OpenStreetMap Nominatim'e gönderilir; koordinat girişi bu aktarımı tamamen atlar.
- Hava kalitesi ölçümleri UHKİA'dan gelir.
- Mesafe, yerel düz-hat (Haversine) hesabıdır — yol/rota mesafesi değildir.
- referans_hkiyerel bir tahmin, enterpolasyon veya ortalama değildir; ilgili istasyonun kaynaktaki resmi değeridir.
- İki saatten eski bir ölçüm, açık bir uyarıyla birlikte yine de döndürülür.
- Bu paket yerel bir stdio yazılımıdır; v1'de merkezi/barındırılan bir servis yoktur.
- locationparametresi il/ilçe yazım hatalarınıget_air_qualitykadar iyi tolere etmez (Nominatim serbest metin araması yapar, il/ilçe fuzzy düzeltmesi yapmaz); sadece bir ilin/ilçenin genel hava kalitesi soruluyorsaget_air_quality/list_stationstercih edilmelidir.
- Nominatim/OpenStreetMap ve UHKİA birbirinden bağımsız, ilişkisiz iki dış servistir.

Bu projeMIT Lisansıile lisanslanmıştır.

You built it, now get users! GoToMarket MCP server