IQAir MCP Server

IQAir のウェブサイトをリバースエンジニアリングして構築された、IQAir のリアルタイム大気質データを公開する MCP サーバーです（公式 API キーは不要）。

ジャカルタの大気質ページ（https://www.iqair.com/id/air-quality/indonesia/jakarta/jakarta）向けに作成されましたが、あらゆる IQAir の場所で動作します。

返される内容

場所ごとに以下が得られます：

• US AQI と 主な汚染物質

• 汚染物質ごとの測定値: PM2.5、PM10、O₃、SO₂（AQI + 濃度）

• 天気: 気温、湿度、気圧、風

• 報告ステーション数

• 7日間および72時間の予報

• 座標 / タイムゾーン

ツール

path は IQAir URL の /<locale>/air-quality/ の後のセグメントです — country/state/city。

仕組み（リバースエンジニアリング）

IQAir は Vercel 上の React Router v7 (Remix) アプリです。すべての大気質ページは、同じ URL に .data サフィックスを付けてローダーペイロードを公開しています：

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

レスポンスは turbo-stream エンコード（遅延プロミスチャンクを持つインデックス参照プール）で、turbo_stream.py によってデコードされます。

アンチボット: Vercel セキュリティチェックポイント

サイトは Vercel のチェックポイントで保護されています。リバースエンジニアリング中に以下のことがわかりました：

• 素の requests / httpx → HTTP 429（チャレンジページ）。

• Chrome TLS 偽装を使用した curl_cffi → 依然として 429（一致する TLS フィンガープリントだけでなく、JS/WASM チャレンジが必要）。

• 有効な _vcrcs クッキーをブラウザ以外のクライアントから再生しても → 429（TLS/JA3 フィンガープリントが検証される）。

• ヘッドレス Chromium → チェックポイントがクリアされない（ヘッドレスが検出される）。

• ヘッドフル Chromium → 約3秒でクリア。

したがって、クライアント（iqair_client.py）は永続プロファイルを持つヘッドフル Chromium を駆動します：チェックポイントを一度解決し、_vcrcs クッキーをプロファイルにキャッシュし、.data フェッチをページコンテキスト内から発行して、ブラウザの実際の TLS スタック + 解決済みクッキーを使用します。ウィンドウは画面外に配置されるため、邪魔になりません。

セットアップ

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

デスクトップセッション / ディスプレイが必要です（ブラウザはヘッドフルで実行する必要があります）。

実行

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

MCP クライアントに登録

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

ファイル

• server.py — ツールを公開する FastMCP サーバー。

• iqair_client.py — ブラウザバックのクライアント（チャレンジ解決 + フェッチ + 正規化）。

• turbo_stream.py — React Router の turbo-stream .data 形式のデコーダー。

• requirements.txt — 依存関係。

RDP 切断をまたいで生存し続ける

チェックポイントはヘッドフルブラウザを強制し、オフスクリーンのヘッドフル Chromium は RDP セッションが切断またはロックされるとレンダリングサーフェスを失う（そして死ぬ）可能性があります。サーバーはこれを2つのレベルで乗り越えます：

1. 自動復旧 — 呼び出しが「target/browser closed」エラーに遭遇した場合、クライアントは死んだブラウザを破棄し、透過的に一度再起動します。

2. ウォッチドッグハートビート — バックグラウンドスレッドが keepalive_seconds（デフォルト 60 秒）ごとにブラウザを ping します。死んでいる/応答がない場合は、事前に再構築してチャレンジを再解決するため、切断によって死んだブラウザが次のツール呼び出しを待つことはありません。復活後のウォームコールは再解決なしで約1〜2秒で返ります。

さらに、現在のユーザーに対してスクリーンセーバー/自動ロックが無効になっています（HKCU\Control Panel\Desktop → ScreenSaveActive=0、ScreenSaveTimeOut=0）。これにより、接続されたセッションがブラウザの下から自分自身をロックアウトしません。これはユーザーごとで、元に戻せます。

完全にコンソールからヘッドレスなセットアップ（誰も接続していないライブデスクトップを維持する）には管理者権限が必要です — HKLM\SOFTWARE\Policies\Microsoft\Windows NT\Terminal Services の下のマシンポリシー MaxDisconnectionTime=0 か、tscon からコンソールへのスケジュールタスクのいずれかです。これらはここでは適用されていません（このドメインアカウントには昇格権限がありません）。ウォッチドッグ + 自動復旧がそれらなしで切断ケースをカバーします。

注意事項と制限

• セッションごとの最初の呼び出しは、一度だけ約3秒のブラウザ起動 + チャレンジ解決を支払います。後続の呼び出しはウォームセッションを再利用します。

• 接続されたデスクトップセッションが依然として推奨されます。ウォッチドッグは再構築によって短い切断/ロックを処理しますが、マシンにはヘッドフルブラウザをレンダリングするためのセッションが必要です。

• データは IQAir が現在公開しているものです（値はリアルタイムで更新されます）。

• これは IQAir の内部（非公開）データエンドポイントに依存しています。サイトの変更により、ルート ID またはデコーダーの更新が必要になる場合があります。

• 個人/教育目的での使用 — IQAir の利用規約を尊重してください。