AI导哈

空气质量数据服务

通过REST API远程访问air-Q云设备的空气质量数据服务，支持实时和历史数据查询、图表绘制及导出功能。

  • by CorantGmbH
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 CorantGmbH/mcp-airq-cloud

使用说明

mcp-airq云

MCP服务器 air-Q 云API-从任何地方访问空气质量数据。

不像 mcp空气质量 （直接与本地网络上的设备通信），此服务器使用 air-Q云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 跨匹配设备

所有工具都是 只读 -云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.Plot命令也可以流式传输 直接到 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)

配置

你需要一个 云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 no 设备API密钥（回退到 AIRQ_CLOUD_API_KEY)
name no 友好名称（默认为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代码

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——请参阅 许可证.

相关 MCP