air-Q

mcp-airq

适用于 air-Q 空气质量传感器设备的 MCP 服务。让 Claude Desktop、Claude Code 和其他 MCP 客户端能够直接查询和配置本地网络中的 air-Q 设备。

基于 aioairq 构建，这是 air-Q 官方的异步 Python 库。

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

安装

pip install mcp-airq

也可以使用 uvx 直接运行：

uvx mcp-airq

命令行用法

在 Shell 中直接使用同一条命令：

mcp-airq list-devices
mcp-airq get-air-quality --device "Living Room"
mcp-airq get-air-quality-history --device "Living Room" --last-hours 12 --sensors co2
mcp-airq plot-air-quality-history --sensor co2 --output-format png
mcp-airq export-air-quality-history --sensor co2 --output-format xlsx
mcp-airq set-night-mode --activated --device "Bedroom"

对于历史图表和导出：

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

命令行子命令与 MCP 工具名称相同。两种方式都可使用：

mcp-airq list-devices
mcp-airq list_devices

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

mcp-airq serve

命令行支持管道：成功执行的命令输出到 stdout，而 工具错误会输出到 stderr，并返回退出码 1。

mcp-airq get-air-quality --device "Living Room" | jq '.co2'
mcp-airq get-air-quality --device "Living Room" --compact-json | jq '.co2'
mcp-airq get-air-quality --device "Living Room" --yaml | yq '.co2'

设备配置

创建一个包含设备信息的 JSON 文件，例如 ~/.config/airq-devices.json：

[
  {"address": "192.168.4.1", "password": "your_password", "name": "air-Q Pro", "location": "Living Room", "group": "Home"},
  {"address": "192.168.4.2", "password": "your_password", "name": "air-Q Radon", "location": "Living Room", "group": "Home"},
  {"address": "office_air-q.local", "password": "other_pass", "name": "Office", "group": "Work"}
]

每个条目都需要：

• address — IP 地址或 mDNS 主机名（例如 abcde_air-q.local）
• password — 设备密码（默认值：airqsetup）
• name（可选）— 易于辨认的名称；默认为地址
• location（可选）— 用于分组的实际房间/区域（例如 "Living Room"）
• group（可选）— 与位置相互独立的第二种分组维度（例如 "Home"、"Work"）

然后限制该文件的访问权限（文件中包含密码）：

chmod 600 ~/.config/airq-devices.json

或者，通过 AIRQ_DEVICES 环境变量以内联 JSON 字符串的形式传入设备列表。

Claude Desktop

将以下内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "airq": {
      "command": "uvx",
      "args": ["mcp-airq"],
      "env": {
        "AIRQ_CONFIG_FILE": "/home/you/.config/airq-devices.json"
      }
    }
  }
}

Claude Code

通过命令行注册一次服务：

claude mcp add airq -e AIRQ_CONFIG_FILE=~/.config/airq-devices.json -- uvx mcp-airq

这会写入 ~/.claude/settings.json，并且 Claude Code VSCode 扩展也会自动读取该配置，无需单独配置。

如果服务无法连接： MCP 服务在子进程中运行，该进程可能不会继承 Shell 的 PATH。请将 uvx 替换为它的完整路径（which uvx → 例如 /home/you/.local/bin/uvx）：

claude mcp add airq -e AIRQ_CONFIG_FILE=~/.config/airq-devices.json -- /home/you/.local/bin/uvx mcp-airq

OpenAI Codex

通过命令行注册一次服务：

codex mcp add airq --env AIRQ_CONFIG_FILE=~/.config/airq-devices.json -- uvx mcp-airq

这会写入 ~/.codex/config.toml，并且 Codex VSCode 扩展也会自动读取该配置。

如果服务无法连接： 请使用 uvx 的完整路径（参见上方说明）。

可用工具

只读

工具	描述
list_devices	列出所有已配置的 air-Q 设备（如果已设置，则包含位置／组）
get_air_quality	获取传感器读数 — 按 device、location 或 group 查询
get_air_quality_history	以面向列的 JSON 格式获取历史传感器数据
plot_air_quality_history	为所有匹配设备中的每个传感器绘制一张历史图表
export_air_quality_history	将所有匹配设备中的一个历史传感器导出为一个 csv／xlsx 文件
get_device_info	获取设备元数据（名称、型号、固件版本）
get_config	获取完整设备配置
get_logs	获取设备日志条目
identify_device	让设备的 LED 闪烁，以便通过视觉识别
get_led_theme	获取当前 LED 可视化主题
get_possible_led_themes	列出所有可用的 LED 可视化主题
get_night_mode	获取当前夜间模式配置
get_brightness_config	获取当前 LED 亮度配置

配置

工具	描述
set_device_name	重命名设备
set_led_theme	更改 LED 可视化内容（CO₂、VOC、湿度、PM2.5、…）
set_night_mode	配置夜间模式的时间安排和设置
set_brightness	调整 LED 亮度（日间／夜间）
configure_network	设置静态 IP 或切换到 DHCP

设备控制

工具	描述
restart_device	重启设备（停机约 30 秒）
shutdown_device	关闭设备（需要手动重启）

多设备支持

配置了多个设备时，请指定要查询的设备：

• 按准确名称："air-Q Pro"
• 按部分匹配（不区分大小写）："pro"、"radon"

如果只配置了一个设备，则会自动选中该设备。

按位置和组查询

get_air_quality 接受两个可选的分组参数：

• location — 查询同一房间中的所有设备（例如 "Living Room"）
• group — 查询共享同一个组标签的所有设备（例如 "Home"）

这两个参数相互独立：设备可以有位置、组、两者都有，或两者都没有。 匹配不区分大小写，并基于子字符串进行。

get_air_quality(location="Living Room")  → air-Q Pro + air-Q Radon
get_air_quality(group="Home")            → air-Q Pro + air-Q Radon + …
get_air_quality(device="air-Q Radon")   → just that one device

每次调用只能指定 device、location 或 group 中的一个。

历史数据

三个工具可用于访问存储在设备 SD 卡上的数据：

绘制图表

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

单台设备（24 小时、面积图、PNG）

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

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

# All devices at a location, custom time range, SVG output
mcp-airq 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 plot-air-quality-history --sensor co2 --dark --chart-type line

# Save to file
mcp-airq 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 export-air-quality-history --sensor co2 --device "Living Room" --last-hours 48

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

查询原始 JSON

get_air_quality_history 会返回按列组织的 JSON，适用于程序化分析。

mcp-airq get-air-quality-history --device "Living Room" --last-hours 12 \
  --sensors co2 pm2_5 --max-points 150

常用参数

参数	默认值	说明
--last-hours	1 (history) / 24 (plot)	要检索的数据小时数
--from-datetime / --to-datetime	—	ISO 8601 时间范围（优先于 --last-hours）
--max-points	300	降采样至最多 N 个均匀分布的数据点
--timezone-name	UTC	时间戳使用的 IANA 时区（例如 Europe/Berlin）

示例提示词

• “客厅的空气质量怎么样？” — 查询该位置的所有设备
• “家里的空气质量怎么样？” — 查询“Home”组中的所有设备
• “将过去 12 小时的 CO₂ 趋势显示为 SVG”
• “将昨天的氡历史记录导出为 Excel”
• “显示氡浓度” — 按名称定位 air-Q Radon 设备
• “在 LED 上显示 CO₂”
• “将夜间模式设为晚上 10 点到早上 7 点”
• “将亮度设为 50%”
• “设备日志里有什么？”
• “让 air-Q 闪烁”

开发

git clone https://github.com/CorantGmbH/mcp-airq.git
cd mcp-airq
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

发布流程

1. 更新 pyproject.toml 中的 version。
2. 提交更改并创建匹配的 Git 标签，例如 v0.1.1。
3. 根据该标签发布 GitHub Release。

发布工作流会验证发布标签是否与 pyproject.toml 匹配，将软件包上传到 PyPI，然后将同一版本发布到 MCP Registry。

许可证

Apache License 2.0 — 详见 LICENSE。