IQAir MCP 服务器

一个 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 是 IQAir URL 中 /<locale>/air-quality/ 之后的部分——country/state/city。

工作原理（逆向工程）

IQAir 是 Vercel 上的 React Router v7 (Remix) 应用。每个空气质量页面都在同一 URL 上以 .data 后缀暴露其 loader 负载：

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（挑战页面）。

• 使用 Chrome TLS 模拟的 curl_cffi → 仍然是 429（需要 JS/WASM 挑战，而不仅仅是匹配的 TLS 指纹）。

• 即使从非浏览器客户端重放有效的 _vcrcs cookie → 429（TLS/JA3 指纹会被验证）。

• 无头 Chromium → 检查点永远不会清除（无头模式会被检测到）。

• 有头 Chromium → 约 ~3 秒清除。

因此，客户端（iqair_client.py）驱动一个带有持久化配置文件的 headful Chromium：它解决一次检查点，将 _vcrcs cookie 缓存在配置文件中，并从页面上下文内部发出 .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 — React Router 的 turbo-stream .data 格式解码器。

• requirements.txt — 依赖项。

在 RDP 断开连接时保持存活

检查点强制使用有头浏览器，而当 RDP 会话断开或锁定时，屏幕外的有头 Chromium 可能会失去其渲染表面（并崩溃）。服务器在两个层面应对这种情况：

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 的服务条款。