mcp-airq 0.1.0

MCP server for direct HTTP communication with air-Q air quality sensor devices

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

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.

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.

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

License

Apache License 2.0 — see LICENSE.