IQAir MCP Server

MCP-сервер, предоставляющий данные о качестве воздуха в реальном времени с IQAir — создан путём обратной разработки сайта IQAir (официальный API-ключ не требуется).

Он был создан для страницы качества воздуха в Джакарте (https://www.iqair.com/id/air-quality/indonesia/jakarta/jakarta), но работает для любой локации IQAir.

Что возвращает

Для локации вы получаете:

• US AQI и основной загрязнитель

• Показатели по каждому загрязнителю: PM2.5, PM10, O₃, SO₂ (AQI + концентрация)

• Погоду: температура, влажность, давление, ветер

• Количество отчитывающихся станций

• Прогнозы на 7 дней и 72 часа

• Координаты / часовой пояс

Инструменты

path — это сегмент после /<locale>/air-quality/ в URL IQAir — country/state/city.

Как это работает (реверс-инжиниринг)

IQAir — это приложение React Router v7 (Remix) на Vercel. Каждая страница качества воздуха предоставляет свои данные загрузчика по тому же URL с суффиксом .data:

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

Ответ закодирован в формате turbo-stream (пул с индексными ссылками и отложенными promise-чанками), декодируется с помощью turbo_stream.py.

Анти-бот: контрольная точка безопасности Vercel

Сайт защищён контрольной точкой Vercel. В ходе обратной разработки мы обнаружили:

• Обычные requests / httpx → HTTP 429 (страница с вызовом).

• curl_cffi с имитацией TLS Chrome → всё ещё 429 (требуется JS/WASM-вызов, а не только совпадение TLS-отпечатка).

• Даже валидный cookie _vcrcs, воспроизведённый из не-браузерного клиента → 429 (проверяется TLS/JA3-отпечаток).

• Безголовый Chromium → контрольная точка никогда не снимается (безголовый режим обнаруживается).

• С головой Chromium → снимается за ~3 с.

Поэтому клиент (iqair_client.py) управляет Chromium с головой и постоянным профилем: он один раз решает контрольную точку, кэширует cookie _vcrcs в профиле и выполняет запрос .data из контекста страницы, чтобы использовались реальный TLS-стек браузера и решённый cookie. Окно размещается за пределами экрана, чтобы не мешать вам.

Установка

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 — декодер формата .data от React Router (turbo-stream).

• requirements.txt — зависимости.

Устойчивость к отключениям RDP

Контрольная точка вынуждает использовать браузер с головой, а безэкранный Chromium с головой может потерять поверхность рендеринга (и умереть) при отключении или блокировке сеанса RDP. Сервер переживает это на двух уровнях:

1. Автовосстановление — если вызов получает ошибку "target/browser closed", клиент уничтожает мёртвый браузер и прозрачно перезапускает его один раз.

2. Сторожевой heartbeat — фоновый поток пингует браузер каждые keepalive_seconds (по умолчанию 60 с); если он мёртв или не отвечает, поток упреждающе пересобирает и заново решает контрольную точку, так что отключение никогда не оставляет мёртвый браузер в ожидании следующего вызова инструмента. Тёплые вызовы после восстановления возвращаются за ~1–2 с без повторного решения.

Дополнительно для текущего пользователя отключены заставка и автоблокировка (HKCU\Control Panel\Desktop → ScreenSaveActive=0, ScreenSaveTimeOut=0), чтобы подключённый сеанс не блокировал сам себя под браузером. Это настраивается для каждого пользователя и обратимо.

Полностью безконсольные настройки (поддержание живого рабочего стола без подключённых пользователей) требуют прав администратора — либо машинная политика MaxDisconnectionTime=0 в HKLM\SOFTWARE\Policies\Microsoft\Windows NT\Terminal Services, либо запланированная задача tscon на консоль. Здесь они не применяются (нет повышения прав для этой доменной учётной записи); сторожевой heartbeat + автовосстановление покрывают случай отключения без них.

Примечания и ограничения

• Первый вызов за сеанс оплачивает разовый запуск браузера ~3 с + решение контрольной точки; последующие вызовы используют тёплую сессию.

• Подключённый сеанс рабочего стола по-прежнему рекомендуется; сторожевой heartbeat обрабатывает кратковременные отключения/блокировки пересборкой, но на машине должен быть сеанс, чтобы вообще отображать браузер с головой.

• Данные — это то, что IQAir публикует в данный момент (значения обновляются в реальном времени).

• Это зависит от внутренней (недокументированной) конечной точки данных IQAir; изменения на сайте могут потребовать обновления идентификатора маршрута или декодера.

• Для личного/образовательного использования — соблюдайте условия обслуживания IQAir.