Server data from the Official MCP Registry
MCP server for direct HTTP communication with air-Q air quality sensor devices
MCP server for direct HTTP communication with air-Q air quality sensor devices
Valid MCP server (1 strong, 2 medium validity signals). 5 known CVEs in dependencies Package registry verified. Imported from the Official MCP Registry.
4 files analyzed · 6 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Set these up before or after installing:
Environment variable: AIRQ_CONFIG_FILE
Environment variable: AIRQ_DEVICES
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-corantgmbh-mcp-airq": {
"env": {
"AIRQ_DEVICES": "your-airq-devices-here",
"AIRQ_CONFIG_FILE": "your-airq-config-file-here"
},
"args": [
"mcp-airq"
],
"command": "uvx"
}
}
}From the project's GitHub README.
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.
pip install mcp-airq
Or run directly with uvx:
uvx mcp-airq
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:
device, location, and group to combine all configured devices into one artifactlocation or group to combine only the matching devicesplot_air_quality_history returns one file per requested sensor, with one series per matching deviceexport_air_quality_history returns one CSV/XLSX file per request, with rows for all matching devicesThe 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'
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 addresslocation (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.
Add to your claude_desktop_config.json:
{
"mcpServers": {
"airq": {
"command": "uvx",
"args": ["mcp-airq"],
"env": {
"AIRQ_CONFIG_FILE": "/home/you/.config/airq-devices.json"
}
}
}
}
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
uvxwith its full path (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
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).
| Tool | Description |
|---|---|
list_devices | List all configured air-Q devices (with location/group if set) |
get_air_quality | Get sensor readings — by device, location, or group |
get_air_quality_history | Get historical sensor data as column-oriented JSON |
plot_air_quality_history | Render one historical chart per sensor across all matching devices |
export_air_quality_history | Export one historical sensor as one csv/xlsx across matching devices |
get_device_info | Get device metadata (name, model, firmware version) |
get_config | Get full device configuration |
get_logs | Get device log entries |
identify_device | Make device blink its LEDs for visual identification |
get_led_theme | Get current LED visualization theme |
get_possible_led_themes | List all available LED visualization themes |
get_night_mode | Get current night mode configuration |
get_brightness_config | Get current LED brightness configuration |
| Tool | Description |
|---|---|
set_device_name | Rename a device |
set_led_theme | Change LED visualization (CO₂, VOC, Humidity, PM2.5, …) |
set_night_mode | Configure night mode schedule and settings |
set_brightness | Adjust LED brightness (day/night) |
configure_network | Set static IP or switch to DHCP |
| Tool | Description |
|---|---|
restart_device | Restart the device (~30s downtime) |
shutdown_device | Shut down the device (manual restart required) |
When multiple devices are configured, specify which device to query:
"air-Q Pro""pro", "radon"If only one device is configured, it is selected automatically.
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.
Three tools provide access to data stored on the device's SD card:
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
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
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
| Parameter | Default | Description |
|---|---|---|
--last-hours | 1 (history) / 24 (plot) | Hours of data to retrieve |
--from-datetime / --to-datetime | — | ISO 8601 time range (overrides --last-hours) |
--max-points | 300 | Downsample to at most N evenly spaced points |
--timezone-name | UTC | IANA timezone for timestamps (e.g. Europe/Berlin) |
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
version in pyproject.toml.v0.1.1.The publish workflow validates that the release tag matches pyproject.toml, uploads the package to PyPI, and then publishes the same version to the MCP Registry.
Apache License 2.0 — see LICENSE.
Be the first to review this server!
by Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
by mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
by Microsoft · Content & Media
Convert files (PDF, Word, Excel, images, audio) to Markdown for LLM consumption
by mcp-marketplace · Developer Tools
Scaffold, build, and publish TypeScript MCP servers to npm — conversationally
by mcp-marketplace · Finance
Free stock data and market news for any MCP-compatible AI assistant.