IQAir MCP Server

Ein MCP-Server, der Echtzeit-Luftqualitätsdaten von IQAir bereitstellt – entwickelt durch Reverse Engineering der IQAir-Website (kein offizieller API-Schlüssel erforderlich).

Er wurde für die Jakarta-Luftqualitätsseite (https://www.iqair.com/id/air-quality/indonesia/jakarta/jakarta) erstellt, funktioniert aber für jeden IQAir-Standort.

Was er zurückgibt

Für einen Standort erhalten Sie:

• US-AQI und der Hauptschadstoff

• Schadstoffwerte pro Schadstoff: PM2.5, PM10, O₃, SO₂ (AQI + Konzentration)

• Wetter: Temperatur, Luftfeuchtigkeit, Druck, Wind

• Anzahl der Messstationen

• 7-Tage- und 72-Stunden-Vorhersagen

• Koordinaten / Zeitzone

Werkzeuge

path ist das Segment nach /<locale>/air-quality/ in einer IQAir-URL – country/state/city.

Wie es funktioniert (Reverse Engineering)

IQAir ist eine React Router v7 (Remix)-App auf Vercel. Jede Luftqualitätsseite stellt ihre Loader-Payload unter derselben URL mit einem .data-Suffix bereit:

GET /id/air-quality/indonesia/jakarta/jakarta.data?_routes=routes%2F%24(locale).air-quality.%24

Die Antwort ist turbo-stream-codiert (ein indexreferenzierter Pool mit verzögerten Promise-Chunks), dekodiert von turbo_stream.py.

Anti-Bot: der Vercel-Sicherheits-Checkpoint

Die Website ist durch den Checkpoint von Vercel geschützt. Beim Reverse Engineering haben wir festgestellt:

• Einfache requests / httpx-Aufrufe → HTTP 429 (Challenge-Seite).

• curl_cffi mit Chrome-TLS-Impersonation → immer noch 429 (JS/WASM-Challenge ist erforderlich, nicht nur ein passender TLS-Fingerabdruck).

• Selbst ein gültiges _vcrcs-Cookie, das von einem Nicht-Browser-Client wiedergegeben wird → 429 (TLS/JA3-Fingerabdruck wird validiert).

• Headless Chromium → Checkpoint wird nie gelöscht (Headless wird erkannt).

• Headful Chromium → wird in ~3 s gelöscht.

Der Client (iqair_client.py) steuert also ein Headful-Chromium mit einem persistenten Profil: Er löst den Checkpoint einmal, speichert das _vcrcs-Cookie im Profil und führt den .data-Abruf aus dem Seitenkontext heraus aus, sodass der echte TLS-Stack des Browsers und das gelöste Cookie verwendet werden. Das Fenster wird außerhalb des Bildschirms platziert, damit es Sie nicht stört.

Einrichtung

cd iqair-mcp
pip install -r requirements.txt
python -m playwright install chromium

Eine Desktop-Sitzung / Anzeige ist erforderlich (der Browser muss headful laufen).

Ausführen

python server.py                    # stdio (for MCP clients)
python server.py --transport sse    # SSE on http://localhost:8000

Bei einem MCP-Client registrieren

{
  "mcpServers": {
    "iqair": {
      "command": "python",
      "args": ["C:\\path-to-mcp\\iqair-mcp\\server.py"]
    }
  }
}

Dateien

• server.py – FastMCP-Server, der die Werkzeuge bereitstellt.

• iqair_client.py – Browser-gestützter Client (Challenge-Lösung + Abruf + Normalisierung).

• turbo_stream.py – Dekoder für das turbo-stream .data-Format von React Router.

• requirements.txt – Abhängigkeiten.

Überleben bei RDP-Trennungen

Der Checkpoint erzwingt einen Headful-Browser, und ein außerhalb des Bildschirms laufendes Headful-Chromium kann seine Rendering-Oberfläche verlieren (und sterben), wenn eine RDP-Sitzung getrennt oder gesperrt wird. Der Server überlebt dies auf zwei Ebenen:

1. Automatische Wiederherstellung – Wenn ein Aufruf auf einen „target/browser closed"-Fehler stößt, reißt der Client den toten Browser ab und startet ihn einmal transparent neu.

2. Watchdog-Heartbeat – Ein Hintergrundthread pingt den Browser alle keepalive_seconds (Standard 60 s); wenn er tot/nicht reagiert, baut er ihn proaktiv neu auf und löst die Challenge erneut, sodass eine Trennung nie einen toten Browser für den nächsten Werkzeugaufruf hinterlässt. Warme Aufrufe nach einer Wiederbelebung kehren in ~1–2 s ohne erneutes Lösen zurück.

Zusätzlich wurden Bildschirmschoner/Auto-Sperre für den aktuellen Benutzer deaktiviert (HKCU\Control Panel\Desktop → ScreenSaveActive=0, ScreenSaveTimeOut=0), damit eine verbundene Sitzung sich nicht unter dem Browser selbst sperrt. Dies ist pro Benutzer und umkehrbar.

Vollständig konsolenlose Setups (eine Live-Desktop-Sitzung mit niemandem verbunden) erfordern Administratorrechte – entweder eine Maschinenrichtlinie MaxDisconnectionTime=0 unter HKLM\SOFTWARE\Policies\Microsoft\Windows NT\Terminal Services oder eine geplante Aufgabe tscon zur Konsole. Diese werden hier nicht angewendet (keine Erhöhung auf diesem Domänenkonto); der Watchdog + die automatische Wiederherstellung decken den Trennungsfall ohne sie ab.

Hinweise & Einschränkungen

• Der erste Aufruf pro Sitzung kostet einen einmaligen ~3 s Browserstart + Challenge-Lösung; nachfolgende Aufrufe nutzen die warme Sitzung.

• Eine verbundene Desktop-Sitzung wird weiterhin empfohlen; der Watchdog behandelt kurze Trennungen/Sperren durch Neuerstellung, aber die Maschine muss eine Sitzung haben, um überhaupt einen Headful-Browser rendern zu können.

• Die Daten sind das, was IQAir derzeit veröffentlicht (Werte werden in Echtzeit aktualisiert).

• Dies verlässt sich auf den internen (undokumentierten) Datenendpunkt von IQAir; Änderungen an der Website können eine Aktualisierung der Routen-ID oder des Dekoders erfordern.

• Für den persönlichen/lehrreichen Gebrauch – respektieren Sie die Nutzungsbedingungen von IQAir.