mcp-airq

MCP server for air-Q air quality sensor devices. Enables Claude Desktop, Claude Code, and other MCP clients to directly query and configure air-Q devices on your local network.

Built on aioairq, the official async Python library for air-Q.

The same mcp-airq executable also works as a direct CLI when you pass a tool name as a subcommand.

Installation

pip install mcp-airq

Or run directly with uvx:

uvx mcp-airq

CLI Usage

Use the same command directly from the 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"

For historical plots and exports:

• omit device, location, and group to combine all configured devices into one artifact
• use location or group to combine only the matching devices
• plot_air_quality_history returns one file per requested sensor, with one series per matching device
• export_air_quality_history returns one CSV/XLSX file per request, with rows for all matching devices

The CLI subcommands mirror the MCP tool names. Both styles work:

mcp-airq list-devices
mcp-airq list_devices

To force MCP server mode from an interactive terminal, run:

mcp-airq serve

The CLI is pipe-friendly: successful command output goes to stdout, while tool errors go to stderr with exit code 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'

Device Configuration

Create a JSON file with your device(s), e.g. ~/.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"}
]

Each entry requires:

• address — IP address or mDNS hostname (e.g. abcde_air-q.local)
• password — Device password (default: airqsetup)
• name (optional) — Human-readable name; defaults to address
• location (optional) — Physical room/area for grouping (e.g. "Living Room")
• group (optional) — Second grouping dimension, orthogonal to location (e.g. "Home", "Work")

Then restrict access to the file (it contains passwords):

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

Alternatively, pass the device list inline via the AIRQ_DEVICES environment variable as a JSON string.

Claude Desktop

Add to your claude_desktop_config.json:

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

Claude Code

Register the server once via the CLI:

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

This writes to ~/.claude/settings.json and is automatically picked up by the Claude Code VSCode extension as well — no separate configuration needed.

If the server fails to connect: MCP servers run in a subprocess that may not inherit your shell's PATH. Replace uvx with its full path (which uvx → e.g. /home/you/.local/bin/uvx):

Terminal

Copy

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

OpenAI Codex

Register the server once via the CLI:

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

This writes to ~/.codex/config.toml and is automatically picked up by the Codex VSCode extension as well.

If the server fails to connect: Use the full path to uvx (see note above).

Available Tools

Read-Only

Configuration

Device Control

Multi-Device Support

When multiple devices are configured, specify which device to query:

• By exact name: "air-Q Pro"
• By partial match (case-insensitive): "pro", "radon"

If only one device is configured, it is selected automatically.

Location and Group Queries

get_air_quality accepts two optional grouping parameters:

• location — query all devices in the same room (e.g. "Living Room")
• group — query all devices sharing a group tag (e.g. "Home")

Both are independent: a device can have a location, a group, both, or neither. Matching is case-insensitive and substring-based.

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

Exactly one of device, location, or group may be specified per call.

Historical Data

Three tools provide access to data stored on the device's SD card:

Plotting charts

plot_air_quality_history renders a chart for one sensor. When multiple devices match, each device becomes a separate series in the same chart.

Single device (24 h, area chart, PNG)

Multiple devices at one location (24 h, area chart, 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

Output formats: png (default), webp, svg, html (interactive Plotly chart with hover tooltips and zoom)

Customization: --title, --x-axis-title, --y-axis-title, --chart-type (line/area), --dark, --timezone-name

Exporting data

export_air_quality_history produces one CSV or Excel file containing all matching devices.

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