air-Q

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):

`bash

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

Excel export for all devices at a location

mcp-airq export-air-quality-history --sensor radon --location "Home" \ --output-format xlsx --output radon.xlsx

Querying raw JSON

get_air_quality_history returns column-oriented JSON, useful for programmatic analysis.

mcp-airq get-air-quality-history --device "Living Room" --last-hours 12 \

--sensors co2 pm2_5 --max-points 150

Common parameters

Example Prompts

• *"How is the air quality in the living room?"* — queries all devices at that location
• *"What's the air quality at home?"* — queries all devices in the "Home" group
• *"Show the CO₂ trend over the last 12 hours as SVG"*
• *"Export the radon history from yesterday as Excel"*
• *"Show me the radon level"* — targets the air-Q Radon device by name
• *"Show CO₂ on the LEDs"*
• *"Enable night mode from 10 PM to 7 AM"*
• *"Set brightness to 50%"*
• *"What's in the device log?"*
• *"Make the air-Q blink"*

Development

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

The repository uses a project-local .venv plus uv.lock for reproducible tooling. Run all developer commands through uv run, for example:

uv run ruff check .

uv run ruff format --check . uv run pyright uv run pre-commit run --all-files

Release Process

1. Update version in pyproject.toml.
2. Commit and create a matching Git tag like v0.1.1.
3. Publish a GitHub Release from that tag.

The publish workflow validates that the release tag matches pyproject.toml, uploads the package to PyPI, and then publishes the same version to the M