Skip to main content

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.

Güncel kararlı sürüm: v1.1.0

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.

Veri kaynakları

  • 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ğerlerini olduğu gibi kullanı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.

Gereksinimler

  • Python 3.11+
  • uv

Kurulum

PyPI üzerinden (önerilen):

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

Depoyu klonlayarak geliştirme amaçlı kurulum:

cd airquality-tr-mcp
uv sync

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

PyPI paketiyle kurulduysa:

{
  "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"
      ]
    }
  }
}

REST API olarak çalıştırma

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 olarak http://localhost:8000 üzerinde dinler. Etkileşimli dokümantasyon için http://localhost:8000/docs adresini 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 (hata alanı dolu yanıtlarda) uygun bir HTTP durum kodu (400/404/409/429/502/504) döndürülmesidir.

Tool'lar

Tool Amaç
ping MCP sürecinin ayakta olup olmadığını kontrol eder
list_stations Aktif UHKİA istasyonlarını listeler
get_air_quality İl özeti ve istasyon bazlı döküm
get_nearest_air_quality Metin veya koordinatla en yakın resmi istasyon verisi
get_station_detail Tek bir istasyonun tam güncel ölçümü
get_historical_data Günlük geçmiş özetleri
get_trend_summary Kural tabanlı 3/6 günlük trend
compare_cities İki il için kompakt karşılaştırma
get_ranking İl seviyesinde sıralama
get_detailed_ranking İstasyon seviyesinde ülke geneli sıralama
get_health_advisory Kural tabanlı il sağlık tavsiyesi
check_alert İstek üzerine HKİ/kirletici eşik kontrolü

get_air_quality ve get_nearest_air_quality farklı amaçlara hizmet eder:

  • get_air_quality — bir ilin özetini ve o ildeki tüm istasyonları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ın ve 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_ranking vs get_detailed_ranking — get_ranking il başına tek temsili değerle hızlı bir sıralama verir; get_detailed_ranking aynı veriyi il bazında özetlemeden, istasyon seviyesinde ülke geneli sıralar.

Örnek çağrılar

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 örnekleri

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

Gizlilik, atıf ve sınırlamalar

  • 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_hki yerel 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.
  • location parametresi il/ilçe yazım hatalarını get_air_quality kadar iyi tolere etmez (Nominatim serbest metin araması yapar, il/ilçe fuzzy düzeltmesi yapmaz); sadece bir ilin/ilçenin genel hava kalitesi soruluyorsa get_air_quality/list_stations tercih edilmelidir.
  • Nominatim/OpenStreetMap ve UHKİA birbirinden bağımsız, ilişkisiz iki dış servistir.

Lisans

Bu proje MIT Lisansı ile lisanslanmıştır.

Metadata

Release files for airquality-tr-mcp 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for airquality-tr-mcp 1.1.0
File Size Uploaded Provenance Actions
airquality_tr_mcp-1.1.0.tar.gz 310.7 kB Without provenance Details for airquality_tr_mcp-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for airquality-tr-mcp 1.1.0
File Interpreter ABI Platform Actions
airquality_tr_mcp-1.1.0-py3-none-any.whl Python 3 none any Details for airquality_tr_mcp-1.1.0-py3-none-any.whl

Total release size: 350.6 kB

Release files / airquality_tr_mcp-1.1.0.tar.gz

Download URL airquality_tr_mcp-1.1.0.tar.gz
Size 310.7 kB
Tags Source
SHA-256 checksum
How to use checksums
9d9afeaa4737a194417777cda9272990f801a6f71b40531282b59243d0bb1c92
BLAKE2b-256 checksum
How to use checksums
aed103fa75710a4ae1303fd28a187840338b6e3c97529703597fbe9f104c0d60
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / airquality_tr_mcp-1.1.0-py3-none-any.whl

Download URL airquality_tr_mcp-1.1.0-py3-none-any.whl
Size 39.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b47e3423b690240294ae6e94a68f301e7ab7271270e9bf4dda20aa4c65fd77b8
BLAKE2b-256 checksum
How to use checksums
86c82daf502e0f5b4d802fee54cd05f45bd74bb1dd78db8e716e81bcd4ab2711
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for airquality-tr-mcp 1.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page