Servidor MCP de IQAir

Un servidor MCP que expone datos de calidad del aire en tiempo real de IQAir — creado mediante ingeniería inversa del sitio web de IQAir (no se requiere ninguna clave API oficial).

Se creó para la página de calidad del aire de Yakarta (https://www.iqair.com/id/air-quality/indonesia/jakarta/jakarta) pero funciona para cualquier ubicación de IQAir.

Qué devuelve

Para una ubicación obtienes:

• US AQI y el contaminante principal

• Lecturas por contaminante: PM2.5, PM10, O₃, SO₂ (AQI + concentración)

• Clima: temperatura, humedad, presión, viento

• Número de estaciones de reporte

• Pronósticos de 7 días y de 72 horas

• Coordenadas / zona horaria

Herramientas

path es el segmento después de /<locale>/air-quality/ en una URL de IQAir — country/state/city.

Cómo funciona (ingeniería inversa)

IQAir es una aplicación React Router v7 (Remix) en Vercel. Cada página de calidad del aire expone su payload de loader en la misma URL con un sufijo .data:

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

La respuesta está codificada en turbo-stream (un conjunto con referencias por índice y fragmentos de promesas diferidas), decodificada por turbo_stream.py.

Anti-bot: el Vercel Security Checkpoint

El sitio está protegido por el checkpoint de Vercel. Durante la ingeniería inversa descubrimos:

• requests / httpx simples → HTTP 429 (página de desafío).

• curl_cffi con suplantación TLS de Chrome → sigue siendo 429 (se requiere el desafío JS/WASM, no solo una huella TLS coincidente).

• Incluso una cookie _vcrcs válida reproducida desde un cliente que no es un navegador → 429 (la huella TLS/JA3 se valida).

• Chromium headless → el checkpoint nunca se supera (se detecta el modo headless).

• Chromium headful → se supera en ~3 s.

Así que el cliente (iqair_client.py) utiliza un Chromium headful con perfil persistente: resuelve el checkpoint una vez, guarda la cookie _vcrcs en el perfil y realiza la solicitud .data desde el contexto de la página para que se usen la pila TLS real del navegador y la cookie resuelta. La ventana se coloca fuera de pantalla para que no te moleste.

Configuración

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

Se requiere una sesión de escritorio / pantalla (el navegador debe ejecutarse en modo headful).

Ejecución

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

Registrar con un cliente MCP

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

Archivos

• server.py — servidor FastMCP que expone las herramientas.

• iqair_client.py — cliente basado en navegador (resolución de desafíos + obtención + normalización).

• turbo_stream.py — decodificador para el formato .data de turbo-stream de React Router.

• requirements.txt — dependencias.

Mantenerse activo ante desconexiones RDP

El checkpoint obliga a usar un navegador headful, y un Chromium headful fuera de pantalla puede perder su superficie de renderizado (y morir) cuando una sesión RDP se desconecta o se bloquea. El servidor sobrevive a esto en dos niveles:

1. Auto-recuperación — si una llamada encuentra un error de "target/browser closed", el cliente destruye el navegador muerto y lo relanza una vez, de forma transparente.

2. Watchdog heartbeat — un hilo en segundo plano hace ping al navegador cada keepalive_seconds (por defecto 60 s); si está muerto o no responde, lo reconstruye y vuelve a resolver el desafío de forma proactiva, de modo que una desconexión nunca deja un navegador muerto esperando la siguiente llamada a una herramienta. Las llamadas en caliente después de una reactivación responden en ~1–2 s sin volver a resolver.

Además, el protector de pantalla / bloqueo automático se deshabilitó para el usuario actual (HKCU\Control Panel\Desktop → ScreenSaveActive=0, ScreenSaveTimeOut=0) para que una sesión conectada no se bloquee y deje al navegador sin soporte. Esto es por usuario y reversible.

Configuraciones totalmente headless-of-console (mantener un escritorio activo con nadie conectado) requieren derechos de administrador: ya sea una directiva de equipo MaxDisconnectionTime=0 en HKLM\SOFTWARE\Policies\Microsoft\Windows NT\Terminal Services, o una tarea programada tscon hacia la consola. No se aplican aquí (sin elevación en esta cuenta de dominio); el watchdog + auto-recuperación cubren el caso de desconexión sin ellos.

Notas y limitaciones

• La primera llamada de cada sesión conlleva un lanzamiento único del navegador de ~3 s más la resolución del desafío; las llamadas posteriores reutilizan la sesión caliente.

• Se sigue recomendando una sesión de escritorio conectada; el watchdog gestiona las desconexiones/bloqueos breves reconstruyendo, pero la máquina debe tener una sesión para poder renderizar un navegador headful en primer lugar.

• Los datos son los que IQAir publica actualmente (los valores se actualizan en tiempo real).

• Esto depende del endpoint interno (no documentado) de datos de IQAir; los cambios en el sitio pueden requerir actualizar el id de ruta o el decodificador.

• Para uso personal/educativo — respeta los términos de servicio de IQAir.