air-Q Cloud

mcp-airq-cloud

用于访问 air-Q Cloud API 的 MCP 服务 — 随时随地获取空气质量数据。

与 mcp-airq（直接与本地网络上的设备通信）不同，此服务使用 air-Q Cloud REST API 远程获取传感器数据。

同一个 mcp-airq-cloud 可执行文件也可以作为直接 CLI 使用，只需将工具名称作为子命令传入。

工具

工具	描述
list_devices	列出已配置的 air-Q Cloud 设备
get_air_quality	获取最新传感器读数（支持选择设备／位置／组）
get_air_quality_history	获取指定时间范围内的历史数据，格式为按列组织的 JSON
plot_air_quality_history	为所有匹配设备中的每个传感器绘制一张历史图表
export_air_quality_history	将所有匹配设备中某个历史传感器的数据导出为一个 csv 或 xlsx 文件

所有工具均为只读 — Cloud API 不支持设备配置或控制。

安装

pip install mcp-airq-cloud

或从源代码安装：

git clone https://github.com/CorantGmbH/mcp-airq-cloud.git
cd mcp-airq-cloud
uv sync --frozen --extra dev

CLI 用法

在 shell 中直接使用相同的命令：

mcp-airq-cloud list-devices
mcp-airq-cloud get-air-quality --device "Living Room"
mcp-airq-cloud get-air-quality-history --device "Living Room" --last-hours 24 --sensors co2 pm2_5
mcp-airq-cloud plot-air-quality-history --sensor co2 --output-format png --output co2.png
mcp-airq-cloud export-air-quality-history --sensor co2 --output-format xlsx --output co2.xlsx

对于历史图表和导出：

• 省略 device、location 和 group，即可将所有已配置设备的数据合并到一个文件中
• 使用 location 或 group，即可只合并匹配的设备
• plot_air_quality_history 会为每个请求的传感器返回一个文件，每个匹配设备对应一个数据系列
• export_air_quality_history 每次请求会返回一个 CSV/XLSX 文件，其中包含所有匹配设备的行

CLI 子命令与 MCP 工具名称一致。以下两种方式均可使用：

mcp-airq-cloud list-devices
mcp-airq-cloud list_devices

若要在交互式终端中强制使用 MCP 服务模式，请运行：

mcp-airq-cloud serve

CLI 支持管道：命令成功时将输出写入 stdout，工具出错时则将错误写入 stderr，并以退出代码 1 结束。绘图命令也可以直接向 stdout 输出数据。

mcp-airq-cloud get-air-quality --device "Living Room" | jq '.co2'
mcp-airq-cloud get-air-quality-history --device "Living Room" --compact-json | jq '.columns.co2'
mcp-airq-cloud get-air-quality-history --device "Living Room" --yaml | yq '.columns.co2'
mcp-airq-cloud plot-air-quality-history --sensor co2 --device "Living Room" --output - > co2.png
mcp-airq-cloud export-air-quality-history --sensor co2 --device "Living Room" --output - > co2.xlsx

历史数据

以下三个工具可通过 air-Q Cloud API 访问历史传感器数据：

绘制图表

plot_air_quality_history 会为一个传感器绘制图表。匹配到多个设备时，每个设备都会作为独立的数据系列显示在同一张图表中。

单个设备（24 小时，面积图，PNG）

同一位置的多个设备（24 小时，面积图，PNG）

# Single device, last 24 hours (default), PNG output (default)
mcp-airq-cloud plot-air-quality-history --sensor co2 --device "Living Room"

# All devices at a location, custom time range, SVG output
mcp-airq-cloud plot-air-quality-history --sensor co2 --location "Living Room" \
  --from-datetime "2026-03-16T00:00:00" --to-datetime "2026-03-17T00:00:00" \
  --output-format svg --output co2.svg

# All configured devices, dark mode, line chart
mcp-airq-cloud plot-air-quality-history --sensor co2 --dark --chart-type line

# Save to file
mcp-airq-cloud plot-air-quality-history --sensor co2 --output co2_chart.png

输出格式： png（默认）、webp、svg、html（带悬停提示和缩放功能的交互式 Plotly 图表）

自定义选项： --title、--x-axis-title、--y-axis-title、--chart-type（折线图／面积图）、--dark、--timezone-name

导出数据

export_air_quality_history 会生成一个 CSV 或 Excel 文件，其中包含所有匹配设备的数据。

# CSV export (default)
mcp-airq-cloud export-air-quality-history --sensor co2 --device "Living Room" --last-hours 48

# Excel export for all devices at a location
mcp-airq-cloud export-air-quality-history --sensor co2 --location "Home" \
  --output-format xlsx --output co2.xlsx

常用参数

参数	默认值	描述
--last-hours	1（历史数据）／24（图表）	要获取的数据小时数
--from-datetime / --to-datetime	—	ISO 8601 时间范围（优先于 --last-hours）
--max-points	300	将数据降采样至最多 N 个等间距数据点
--timezone-name	UTC	时间戳使用的 IANA 时区（例如 Europe/Berlin）

配置

你需要 Cloud API 密钥和每台设备的 32 位设备 ID。两者都可以在 my.air-q.com 获取。

选项 1：环境变量（内联 JSON）

export AIRQ_CLOUD_DEVICES='[{"id": "de45d2ed777780c96c0deae7a220b745", "api_key": "your-api-key", "name": "Living Room"}]'

选项 2：默认配置文件（推荐）

将 JSON 文件放在 ~/.config/airq-cloud-devices.json — 无需环境变量：

[
  {"id": "de45d2ed777780c96c0deae7a220b745", "api_key": "your-api-key", "name": "Living Room"}
]

选项 3：自定义配置文件路径

export AIRQ_CLOUD_CONFIG_FILE=/path/to/devices.json

选项 4：全局 API 密钥

如果所有设备共用同一个 API 密钥，只需设置一次：

export AIRQ_CLOUD_API_KEY="your-api-key"
export AIRQ_CLOUD_DEVICES='[{"id": "de45d2ed777780c96c0deae7a220b745", "name": "Living Room"}]'

设备配置字段

字段	必填	描述
id	是	32 位云设备 ID
api_key	否	单设备 API 密钥（未设置时使用 AIRQ_CLOUD_API_KEY）
name	否	便于识别的名称（默认为 ID 的前 8 个字符）
location	否	用于分组的位置（例如 "Wohnzimmer"）
group	否	用于分组的组别（例如 "zu Hause"）

与 Claude Desktop 搭配使用

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "air-Q Cloud": {
      "command": "mcp-airq-cloud",
      "env": {
        "AIRQ_CLOUD_DEVICES": "[{\"id\": \"<device-id>\", \"api_key\": \"<key>\", \"name\": \"Living Room\"}]"
      }
    }
  }
}

与 Claude Code 搭配使用

claude mcp add air-Q-Cloud mcp-airq-cloud \
  -e AIRQ_CLOUD_DEVICES='[{"id":"<ID>","api_key":"<KEY>","name":"<Name>"}]'

开发

uv sync --frozen --extra dev
uv run pre-commit install
uv run pytest

该仓库使用项目本地 .venv 和 uv.lock 来确保工具链可复现。通过 uv run 运行开发命令，例如：

uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pre-commit run --all-files

许可证

Apache 2.0 — 参见 LICENSE。