MCP Airq

mcp空气质量

 ](https://pepy.tech/project/mcp-airq)    

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): ``bash 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 （见上文注释）。

可用工具

只读

配置

设备控制

多设备支持

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

• 按确切名称： "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 为一个传感器绘制图表。当多个设备 如果匹配，每个设备都会在同一图表中成为一个单独的系列。

CO₂ area chart — single device

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

CO₂ area chart — multiple devices

*一个位置有多个设备（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

常见参数

示例提示

• *“客厅的空气质量怎么样？”* --查询该位置的所有设备
• *“家里的空气质量怎么样？”* --查询“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

发布过程

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

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

许可证

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