air-Q

Permite el acceso local fácil a los dispositivos air-Q para recuperar datos de calidad del aire.

Documentación

mcp-airq

Servidor MCP para dispositivos de sensor de calidad del aire air-Q. Permite que Claude Desktop, Claude Code y otros clientes MCP consulten y configuren directamente dispositivos air-Q en tu red local.

Construido sobre aioairq, la biblioteca oficial asíncrona de Python para air-Q.

El mismo ejecutable mcp-airq también funciona como CLI directo cuando pasas un nombre de herramienta como subcomando.

Instalación

pip install mcp-airq

O ejecútalo directamente con uvx:

uvx mcp-airq

Uso desde CLI

Usa el mismo comando directamente desde la terminal:

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"

Para gráficos históricos y exportaciones:

omite device, location y group para combinar todos los dispositivos configurados en un solo artefacto
usa location o group para combinar solo los dispositivos que coincidan
plot_air_quality_history devuelve un archivo por sensor solicitado, con una serie por dispositivo que coincida
export_air_quality_history devuelve un archivo CSV/XLSX por solicitud, con filas para todos los dispositivos que coincidan

Los subcomandos del CLI reflejan los nombres de las herramientas MCP. Ambos estilos funcionan:

mcp-airq list-devices
mcp-airq list_devices

Para forzar el modo servidor MCP desde una terminal interactiva, ejecuta:

mcp-airq serve

El CLI es compatible con tuberías: la salida exitosa del comando va a stdout, mientras que los errores de herramientas van a stderr con código de salida 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'

Configuración de dispositivos

Crea un archivo JSON con tus dispositivos, por ejemplo ~/.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"}
]

Cada entrada requiere:

address — Dirección IP o nombre de host mDNS (por ejemplo, abcde_air-q.local)
password — Contraseña del dispositivo (predeterminada: airqsetup)
name (opcional) — Nombre legible; por defecto usa la dirección
location (opcional) — Habitación/área física para agrupar (por ejemplo, "Living Room")
group (opcional) — Segunda dimensión de agrupación, ortogonal a la ubicación (por ejemplo, "Home", "Work")

Luego restringe el acceso al archivo (contiene contraseñas):

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

Alternativamente, pasa la lista de dispositivos en línea mediante la variable de entorno AIRQ_DEVICES como una cadena JSON.

Claude Desktop

Agrega a tu claude_desktop_config.json:

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

Claude Code

Registra el servidor una vez mediante el CLI:

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

Esto escribe en ~/.claude/settings.json y la extensión de Claude Code para VSCode lo detecta automáticamente — no se necesita configuración adicional.

Si el servidor no puede conectarse: Los servidores MCP se ejecutan en un subproceso que puede no heredar el PATH de tu shell. Reemplaza uvx con su ruta completa (which uvx → por ejemplo, /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

Registra el servidor una vez mediante el CLI:

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

Esto escribe en ~/.codex/config.toml y la extensión de Codex para VSCode también lo detecta automáticamente.

Si el servidor no puede conectarse: Usa la ruta completa a uvx (consulta la nota anterior).

Herramientas disponibles

Solo lectura

Herramienta	Descripción
`list_devices`	Lista todos los dispositivos air-Q configurados (con ubicación/grupo si está definido)
`get_air_quality`	Obtiene lecturas de sensores — por `device`, `location` o `group`
`get_air_quality_history`	Obtiene datos históricos de sensores como JSON orientado a columnas
`plot_air_quality_history`	Renderiza un gráfico histórico por sensor en todos los dispositivos que coincidan
`export_air_quality_history`	Exporta un sensor histórico como un `csv`/`xlsx` en los dispositivos que coincidan
`get_device_info`	Obtiene metadatos del dispositivo (nombre, modelo, versión de firmware)
`get_config`	Obtiene la configuración completa del dispositivo
`get_logs`	Obtiene las entradas del registro del dispositivo
`identify_device`	Hace que el dispositivo parpadee sus LEDs para identificación visual
`get_led_theme`	Obtiene el tema actual de visualización LED
`get_possible_led_themes`	Lista todos los temas de visualización LED disponibles
`get_night_mode`	Obtiene la configuración actual del modo nocturno
`get_brightness_config`	Obtiene la configuración actual de brillo de los LEDs

Configuración

Herramienta	Descripción
`set_device_name`	Renombra un dispositivo
`set_led_theme`	Cambia la visualización LED (CO₂, VOC, Humedad, PM2.5, …)
`set_night_mode`	Configura el horario y ajustes del modo nocturno
`set_brightness`	Ajusta el brillo de los LEDs (día/noche)
`configure_network`	Establece IP estática o cambia a DHCP

Control del dispositivo

Herramienta	Descripción
`restart_device`	Reinicia el dispositivo (~30 s de inactividad)
`shutdown_device`	Apaga el dispositivo (requiere reinicio manual)

Soporte para múltiples dispositivos

Cuando hay varios dispositivos configurados, especifica cuál consultar:

Por nombre exacto: "air-Q Pro"
Por coincidencia parcial (sin distinguir mayúsculas): "pro", "radon"

Si solo hay un dispositivo configurado, se selecciona automáticamente.

Consultas por ubicación y grupo

get_air_quality acepta dos parámetros de agrupación opcionales:

location — consulta todos los dispositivos en la misma habitación (por ejemplo, "Living Room")
group — consulta todos los dispositivos que compartan una etiqueta de grupo (por ejemplo, "Home")

Ambos son independientes: un dispositivo puede tener ubicación, grupo, ambos o ninguno. La coincidencia no distingue mayúsculas y se basa en subcadenas.

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

Solo se puede especificar exactamente uno de device, location o group por llamada.

Datos históricos

Tres herramientas brindan acceso a los datos almacenados en la tarjeta SD del dispositivo:

Generación de gráficos

plot_air_quality_history renderiza un gráfico para un sensor. Cuando varios dispositivos coinciden, cada dispositivo se convierte en una serie separada en el mismo gráfico.

CO₂ area chart — single device

Dispositivo único (24 h, gráfico de área, PNG)

CO₂ area chart — multiple devices

Varios dispositivos en una ubicación (24 h, gráfico de área, 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

Formatos de salida: png (predeterminado), webp, svg, html (gráfico interactivo de Plotly con información al pasar el cursor y zoom)

Personalización: --title, --x-axis-title, --y-axis-title, --chart-type (línea/área), --dark, --timezone-name

Exportación de datos

export_air_quality_history produce un archivo CSV o Excel que contiene todos los dispositivos que coincidan.

# 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

Consulta de JSON sin procesar

get_air_quality_history devuelve JSON orientado a columnas, útil para análisis programático.

mcp-airq get-air-quality-history --device "Living Room" --last-hours 12 \
  --sensors co2 pm2_5 --max-points 150

Parámetros comunes

Parámetro	Predeterminado	Descripción
`--last-hours`	1 (historial) / 24 (gráfico)	Horas de datos a recuperar
`--from-datetime` / `--to-datetime`	—	Rango de tiempo ISO 8601 (anula `--last-hours`)
`--max-points`	300	Reduce la muestra a como máximo N puntos espaciados uniformemente
`--timezone-name`	UTC	Zona horaria IANA para marcas de tiempo (por ejemplo, `Europe/Berlin`)

Ejemplos de indicaciones

"¿Cómo está la calidad del aire en la sala de estar?" — consulta todos los dispositivos en esa ubicación
"¿Cuál es la calidad del aire en casa?" — consulta todos los dispositivos en el grupo "Hogar"
"Muestra la tendencia de CO₂ de las últimas 12 horas como SVG"
"Exporta el historial de radón de ayer como Excel"
"Muéstrame el nivel de radón" — apunta al dispositivo air-Q Radon por nombre
"Muestra CO₂ en los LEDs"
"Activa el modo nocturno de 10 PM a 7 AM"
"Establece el brillo al 50%"
"¿Qué hay en el registro del dispositivo?"
"Haz que el air-Q parpadee"

Desarrollo

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

El repositorio usa un .venv local al proyecto junto con uv.lock para herramientas reproducibles. Ejecuta todos los comandos de desarrollo mediante uv run, por ejemplo:

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

Proceso de publicación

Actualiza version en pyproject.toml.
Haz un commit y crea una etiqueta Git coincidente como v0.1.1.
Publica un lanzamiento de GitHub desde esa etiqueta.

El flujo de trabajo de publicación valida que la etiqueta de lanzamiento coincida con pyproject.toml, sube el paquete a PyPI y luego publica la misma versión en el Registro MCP.

Licencia

Licencia Apache 2.0 — consulta LICENSE.