使用说明

mcp空气质量

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

建立在 aioairq，air-Q的官方异步Python库。

相同 mcp-airq 当您传递工具时，可执行文件也可以作为直接CLI使用 name作为子命令。

安装

pip install mcp-airq

或者直接与 uvx:

uvx mcp-airq

CLI使用情况

直接从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文件，其中包含所有匹配设备的行

CLI子命令反映了MCP工具名称。两种风格都适用：

mcp-airq list-devices
mcp-airq list_devices

要从交互式终端强制MCP服务器模式，请运行：

mcp-airq serve

CLI是管道友好的：成功的命令输出将转到 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_config.json:

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

克劳德代码

通过CLI注册服务器一次：

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

这封信是写给 ~/.claude/settings.json 并且被自动拾取 克劳德代码VSCode扩展 也不需要单独的配置。

如果服务器无法连接： MCP服务器在可能不继承shell PATH的子进程中运行。替换 uvx 完整的路径(which uvx → e.g. /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 代码专家

通过CLI注册服务器一次：

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（历史）/24（绘图）	检索数据的小时数
`--from-datetime` / `--to-datetime`	--	ISO 8601时间范围（覆盖 `--last-hours`)
`--max-points`	300	向下采样至最多N个等距点
`--timezone-name`	UTC	IANA时间戳时区（例如。 `Europe/Berlin`)

示例提示

“客厅的空气质量怎么样？” --查询该位置的所有设备
“家里的空气质量怎么样？” --查询“Home”组中的所有设备
“显示CO₂ SVG在过去12小时的趋势”
“将昨天的氡历史导出为Excel”
“给我看看氡水平” --按名称瞄准空气Q氡装置
“显示CO₂ 在LED上”
“从晚上10点到早上7点启用夜间模式”
“将亮度设置为50%”
“设备日志中有什么？”
“让空气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

发布过程

更新 version 在 pyproject.toml.
提交并创建一个匹配的Git标签，如下所示 v0.1.1.
从该标签发布GitHub版本。

发布工作流验证发布标记是否匹配 pyproject.toml，将包上传到PyPI，然后将相同版本发布到MCP注册表。

许可证

Apache许可证2.0——请参阅许可证.

使用说明

mcp空气质量

安装

CLI使用情况

设备配置

克劳德桌面版

克劳德代码

OpenAI 代码专家

可用工具

只读

配置

设备控制

多设备支持

位置和组查询

历史数据

绘制图表

导出数据

查询原始JSON

常见参数

示例提示

发展

发布过程

许可证

相关 MCP

空气质量数据服务

天气数据集成服务

天气数据服务

天气数据服务

气象数据服务器

天气数据服务