air-Q

mcp-airq

air-Q の空気質センサーデバイス用 MCP サーバーです。Claude Desktop、Claude Code、その他の MCP クライアントから、ローカルネットワーク上の air-Q デバイスを直接照会・設定できます。

air-Q 公式の非同期 Python ライブラリである aioairq を基盤としています。

同じ mcp-airq 実行ファイルは、ツール名をサブコマンドとして指定すれば、直接 CLI としても使用できます。

インストール

pip install mcp-airq

uvx を使って直接実行することもできます。

uvx mcp-airq

CLI の使用方法

同じコマンドをシェルから直接使用できます。

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"

過去のデータのプロットやエクスポートを行う場合：

• device、location、group を省略すると、設定済みのすべてのデバイスをまとめて1つの成果物にします
• location または group を使うと、一致するデバイスのみをまとめます
• plot_air_quality_history は、指定したセンサーごとに1つのファイルを返し、一致するデバイスごとに1つの系列を含みます
• export_air_quality_history は、リクエストごとに1つの CSV/XLSX ファイルを返し、一致するすべてのデバイスの行を含みます

CLI のサブコマンドは MCP ツール名に対応しています。どちらの形式も使用できます。

mcp-airq list-devices
mcp-airq list_devices

対話型ターミナルから MCP サーバーモードを強制するには、次のコマンドを実行します。

mcp-airq serve

CLI はパイプでの使用に対応しています。コマンドが成功した場合の出力は stdout に、ツールエラーは終了コード 1 とともに stderr に出力されます。

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'

デバイスの設定

デバイスを記述した JSON ファイルを作成します。例：~/.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"}
]

各エントリには次の項目が必要です。

• address — IP アドレスまたは mDNS ホスト名（例：abcde_air-q.local）
• password — デバイスのパスワード（デフォルト：airqsetup）
• name（任意）— 人が読みやすい名前。デフォルトはアドレスです
• location（任意）— グループ分けに使用する物理的な部屋／エリア（例："Living Room"）
• group（任意）— location とは独立した第2のグループ分け項目（例："Home"、"Work"）

次に、ファイルにはパスワードが含まれているため、アクセスを制限します。

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

または、AIRQ_DEVICES 環境変数に JSON 文字列としてデバイスリストを直接渡すこともできます。

Claude Desktop

claude_desktop_config.json に追加します。

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

Claude Code

CLI からサーバーを一度登録します。

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

この設定は ~/.claude/settings.json に書き込まれ、Claude Code VSCode extension にも自動的に反映されます。別途設定する必要はありません。

サーバーへの接続に失敗する場合： MCP サーバーはシェルの PATH を引き継がないことがあるサブプロセスで実行されます。uvx をフルパスに置き換えてください（which uvx → 例：/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

CLI からサーバーを一度登録します。

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

この設定は ~/.codex/config.toml に書き込まれ、Codex VSCode extension にも自動的に反映されます。

サーバーへの接続に失敗する場合： 上記の注記を参考に、uvx のフルパスを使用してください。

利用可能なツール

読み取り専用

ツール	説明
list_devices	設定済みのすべての air-Q デバイスを一覧表示します（設定されている場合は場所／グループも表示）
get_air_quality	センサーの測定値を取得します — device、location、または group で指定します
get_air_quality_history	過去のセンサーデータを列指向の JSON として取得します
plot_air_quality_history	条件に一致するすべてのデバイスについて、センサーごとに過去のグラフを 1 つ描画します
export_air_quality_history	条件に一致するデバイスの過去のセンサー情報を 1 つの csv／xlsx としてエクスポートします
get_device_info	デバイスのメタデータ（名前、モデル、ファームウェアのバージョン）を取得します
get_config	デバイスの設定全体を取得します
get_logs	デバイスのログエントリーを取得します
identify_device	目視で識別できるようにデバイスの LED を点滅させます
get_led_theme	現在の LED 表示テーマを取得します
get_possible_led_themes	利用可能な LED 表示テーマをすべて一覧表示します
get_night_mode	現在のナイトモード設定を取得します
get_brightness_config	現在の LED 輝度設定を取得します

設定

ツール	説明
set_device_name	デバイスの名前を変更します
set_led_theme	LED の表示テーマを変更します（CO₂、VOC、湿度、PM2.5、…）
set_night_mode	ナイトモードのスケジュールと設定を構成します
set_brightness	LED の輝度を調整します（昼／夜）
configure_network	固定 IP を設定するか、DHCP に切り替えます

デバイス制御

ツール	説明
restart_device	デバイスを再起動します（約 30 秒間停止します）
shutdown_device	デバイスをシャットダウンします（手動での再起動が必要です）

マルチデバイス対応

複数のデバイスが設定されている場合は、照会するデバイスを指定します。

• 完全一致する名前で指定する場合："air-Q Pro"
• 部分一致（大文字と小文字を区別しません）で指定する場合："pro"、"radon"

設定されているデバイスが 1 台のみの場合は、自動的に選択されます。

場所とグループによる照会

get_air_quality は、次の 2 つの任意のグループ化パラメーターを受け付けます。

• location — 同じ部屋にあるすべてのデバイスを照会します（例："Living Room"）
• group — 同じグループタグが付いたすべてのデバイスを照会します（例："Home"）

これらはそれぞれ独立しており、デバイスには場所のみ、グループのみ、両方、またはいずれも設定できます。 一致判定では大文字と小文字を区別せず、部分一致で検索します。

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

1 回の呼び出しで指定できるのは、device、location、group のいずれか 1 つだけです。

過去のデータ

デバイスの SD カードに保存されたデータには、3 つのツールでアクセスできます。

グラフの描画

plot_air_quality_history は、1 つのセンサーのグラフを描画します。複数のデバイスが 一致する場合は、同じグラフに各デバイスを個別の系列として表示します。

単一デバイス（24 時間、面グラフ、PNG）

1 つの場所にある複数のデバイス（24 時間、面グラフ、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

出力形式： png（デフォルト）、webp、svg、html（ホバーツールチップとズーム機能を備えたインタラクティブな Plotly グラフ）

カスタマイズ： --title、--x-axis-title、--y-axis-title、--chart-type（line／area）、--dark、--timezone-name

データのエクスポート

export_air_quality_history は、条件に一致するすべてのデバイスを含む CSV ファイルまたは Excel ファイルを 1 つ生成します。

# 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

生の JSON のクエリ

get_air_quality_history は、プログラムによる分析に便利な列指向の JSON を返します。

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

共通パラメーター

パラメーター	デフォルト	説明
--last-hours	1 (history) / 24 (plot)	取得するデータの時間数
--from-datetime / --to-datetime	—	ISO 8601 の時間範囲（--last-hours を上書きします）
--max-points	300	均等間隔の最大 N 点にダウンサンプリングします
--timezone-name	UTC	タイムスタンプに使用する IANA タイムゾーン（例：Europe/Berlin）

プロンプト例

• 「リビングルームの空気質はどうですか？」 — その場所にあるすべてのデバイスに問い合わせます
• 「自宅の空気質はどうですか？」 — 「Home」グループにあるすべてのデバイスに問い合わせます
• 「過去 12 時間の CO₂ の推移を SVG で表示して」
• 「昨日のラドンの履歴を Excel でエクスポートして」
• 「ラドン濃度を表示して」 — 名前で air-Q Radon デバイスを対象にします
• 「LED に CO₂ を表示して」
• 「午後 10 時から午前 7 時までナイトモードを有効にして」
• 「明るさを 50% に設定して」
• 「デバイスログには何が記録されていますか？」
• 「air-Q を点滅させて」

開発

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

このリポジトリでは、再現可能なツール環境のために、プロジェクト内の .venv と uv.lock を使用しています。 すべての開発コマンドは uv run 経由で実行します。例：

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

リリースプロセス

1. pyproject.toml の version を更新します。
2. コミットし、一致する v0.1.1 のような Git タグを作成します。
3. そのタグから GitHub Release を公開します。

公開ワークフローでは、リリースタグが pyproject.toml と一致することを検証し、パッケージを PyPI にアップロードした後、同じバージョンを MCP Registry に公開します。

ライセンス

Apache License 2.0 — LICENSE を参照してください。