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.

Installation

pip install mcp-airq

Or run directly with uvx:

uvx mcp-airq

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": "Living Room"},
  {"address": "office_air-q.local", "password": "other_pass", "name": "Office"}
]

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

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

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):
claude mcp add airq -e AIRQ_CONFIG_FILE=~/.config/airq-devices.json -- /home/you/.local/bin/uvx mcp-airq

OpenAI Codex

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

Tool	Description
`list_devices`	List all configured air-Q devices
`get_air_quality`	Get current sensor readings (temperature, CO₂, humidity, PM, VOC, …)
`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

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

Device Control

Tool	Description
`restart_device`	Restart the device (~30s downtime)
`shutdown_device`	Shut down the device (manual restart required)

Multi-Device Support

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

By exact name: "Living Room"
By partial match (case-insensitive): "living", "office"

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

Example Prompts

"How is the air quality in the living room?"
"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
pip install -e ".[dev]"
pytest

Release Process

Update version in pyproject.toml.
Commit and create a matching Git tag like v0.1.1.
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 MCP Registry.

License

Apache License 2.0 — see LICENSE.

air-Q

Quick Install