air-Q

Permite acesso local fácil aos dispositivos air-Q para recuperar dados de qualidade do ar.

GitHubExperimente este MCPPatrocinado

Documentação

mcp-airq

MCP PyPI Total Downloads Python License Tests Coverage

Servidor MCP para dispositivos de sensor de qualidade do ar air-Q. Permite que o Claude Desktop, o Claude Code e outros clientes MCP consultem e configurem diretamente dispositivos air-Q na sua rede local.

Construído sobre aioairq, a biblioteca Python assíncrona oficial para air-Q.

O mesmo executável mcp-airq também funciona como CLI direto quando você passa um nome de ferramenta como subcomando.

Instalação

pip install mcp-airq

Ou execute diretamente com uvx:

uvx mcp-airq

Uso via CLI

Use o mesmo comando diretamente no 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"

Para gráficos históricos e exportações:

  • omita device, location e group para combinar todos os dispositivos configurados em um único artefato
  • use location ou group para combinar apenas os dispositivos correspondentes
  • plot_air_quality_history retorna um arquivo por sensor solicitado, com uma série por dispositivo correspondente
  • export_air_quality_history retorna um arquivo CSV/XLSX por solicitação, com linhas para todos os dispositivos correspondentes

Os subcomandos da CLI espelham os nomes das ferramentas MCP. Ambos os estilos funcionam:

mcp-airq list-devices
mcp-airq list_devices

Para forçar o modo servidor MCP a partir de um terminal interativo, execute:

mcp-airq serve

A CLI é compatível com pipes: a saída de comandos bem-sucedidos vai para stdout, enquanto erros de ferramentas vão para stderr com código de saída 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'

Configuração de Dispositivos

Crie um arquivo JSON com seu(s) dispositivo(s), ex.: ~/.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 requer:

  • address — Endereço IP ou hostname mDNS (ex.: abcde_air-q.local)
  • password — Senha do dispositivo (padrão: airqsetup)
  • name (opcional) — Nome legível; o padrão é o endereço
  • location (opcional) — Cômodo/área física para agrupamento (ex.: "Living Room")
  • group (opcional) — Segunda dimensão de agrupamento, ortogonal à localização (ex.: "Home", "Work")

Em seguida, restrinja o acesso ao arquivo (ele contém senhas):

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

Alternativamente, passe a lista de dispositivos inline via a variável de ambiente AIRQ_DEVICES como uma string JSON.

Claude Desktop

Adicione ao seu claude_desktop_config.json:

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

Claude Code

Registre o servidor uma vez via CLI:

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

Isso grava em ~/.claude/settings.json e é detectado automaticamente pela extensão Claude Code VSCode também — nenhuma configuração separada é necessária.

Se o servidor falhar ao conectar: Os servidores MCP rodam em um subprocesso que pode não herdar o PATH do seu shell. Substitua uvx pelo caminho completo (which uvx → ex.: /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

Registre o servidor uma vez via CLI:

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

Isso grava em ~/.codex/config.toml e é detectado automaticamente pela extensão Codex VSCode também.

Se o servidor falhar ao conectar: Use o caminho completo para uvx (veja a nota acima).

Ferramentas Disponíveis

Somente Leitura

FerramentaDescrição
list_devicesLista todos os dispositivos air-Q configurados (com localização/grupo se definido)
get_air_qualityObtém leituras do sensor — por device, location ou group
get_air_quality_historyObtém dados históricos do sensor como JSON orientado a colunas
plot_air_quality_historyRenderiza um gráfico histórico por sensor em todos os dispositivos correspondentes
export_air_quality_historyExporta um sensor histórico como um csv/xlsx entre dispositivos correspondentes
get_device_infoObtém metadados do dispositivo (nome, modelo, versão do firmware)
get_configObtém a configuração completa do dispositivo
get_logsObtém entradas de log do dispositivo
identify_deviceFaz o dispositivo piscar seus LEDs para identificação visual
get_led_themeObtém o tema atual de visualização de LED
get_possible_led_themesLista todos os temas de visualização de LED disponíveis
get_night_modeObtém a configuração atual do modo noturno
get_brightness_configObtém a configuração atual de brilho dos LEDs

Configuração

FerramentaDescrição
set_device_nameRenomeia um dispositivo
set_led_themeAltera a visualização de LED (CO₂, VOC, Umidade, PM2.5, …)
set_night_modeConfigura o agendamento e as configurações do modo noturno
set_brightnessAjusta o brilho dos LEDs (dia/noite)
configure_networkDefine IP estático ou alterna para DHCP

Controle de Dispositivos

FerramentaDescrição
restart_deviceReinicia o dispositivo (~30s de indisponibilidade)
shutdown_deviceDesliga o dispositivo (reinicialização manual necessária)

Suporte a Múltiplos Dispositivos

Quando vários dispositivos estão configurados, especifique qual dispositivo consultar:

  • Por nome exato: "air-Q Pro"
  • Por correspondência parcial (sem diferenciar maiúsculas/minúsculas): "pro", "radon"

Se apenas um dispositivo estiver configurado, ele é selecionado automaticamente.

Consultas por Localização e Grupo

get_air_quality aceita dois parâmetros de agrupamento opcionais:

  • location — consulta todos os dispositivos no mesmo cômodo (ex.: "Living Room")
  • group — consulta todos os dispositivos que compartilham uma tag de grupo (ex.: "Home")

Ambos são independentes: um dispositivo pode ter localização, grupo, ambos ou nenhum. A correspondência não diferencia maiúsculas/minúsculas e é baseada em substrings.

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

Exatamente um de device, location ou group pode ser especificado por chamada.

Dados Históricos

Três ferramentas fornecem acesso aos dados armazenados no cartão SD do dispositivo:

Gerando gráficos

plot_air_quality_history renderiza um gráfico para um sensor. Quando vários dispositivos correspondem, cada dispositivo se torna uma série separada no mesmo gráfico.

CO₂ area chart — single device

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

CO₂ area chart — multiple devices

Vários dispositivos em uma localização (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 saída: png (padrão), webp, svg, html (gráfico Plotly interativo com dicas de ferramentas e zoom)

Personalização: --title, --x-axis-title, --y-axis-title, --chart-type (linha/área), --dark, --timezone-name

Exportando dados

export_air_quality_history produz um arquivo CSV ou Excel contendo todos os dispositivos correspondentes.

# 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

Consultando JSON bruto

get_air_quality_history retorna JSON orientado a colunas, útil para análise programática.

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

Parâmetros comuns

ParâmetroPadrãoDescrição
--last-hours1 (histórico) / 24 (gráfico)Horas de dados a recuperar
--from-datetime / --to-datetime—Intervalo de tempo ISO 8601 (substitui --last-hours)
--max-points300Reduz a amostragem para no máximo N pontos igualmente espaçados
--timezone-nameUTCFuso horário IANA para timestamps (ex.: Europe/Berlin)

Exemplos de Prompts

  • "Como está a qualidade do ar na sala de estar?" — consulta todos os dispositivos naquela localização
  • "Qual é a qualidade do ar em casa?" — consulta todos os dispositivos no grupo "Casa"
  • "Mostre a tendência de CO₂ nas últimas 12 horas como SVG"
  • "Exporte o histórico de radônio de ontem como Excel"
  • "Mostre-me o nível de radônio" — direciona o dispositivo air-Q Radon pelo nome
  • "Mostre CO₂ nos LEDs"
  • "Ative o modo noturno das 22h às 7h"
  • "Defina o brilho para 50%"
  • "O que há no log do dispositivo?"
  • "Faça o air-Q piscar"

Desenvolvimento

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

O repositório usa um .venv local ao projeto, além de uv.lock para ferramentas reproduzíveis. Execute todos os comandos de desenvolvimento através de uv run, por exemplo:

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

Processo de Release

  1. Atualize version em pyproject.toml.
  2. Faça commit e crie uma tag Git correspondente, como v0.1.1.
  3. Publique um GitHub Release a partir dessa tag.

O workflow de publicação valida se a tag do release corresponde a pyproject.toml, envia o pacote para o PyPI e depois publica a mesma versão no MCP Registry.

Licença

Apache License 2.0 — veja LICENSE.