air-Q Cloud

mcp-airq-cloud

air-Q Cloud API 用の MCP サーバーです。どこからでも空気質データにアクセスできます。

mcp-airq（ローカルネットワーク上のデバイスと直接通信します）とは異なり、このサーバーは air-Q Cloud REST API を使ってセンサーデータをリモートで取得します。

同じ mcp-airq-cloud 実行ファイルは、ツール名をサブコマンドとして指定すると、直接 CLI としても動作します。

ツール

ツール	説明
list_devices	設定済みの air-Q Cloud デバイスを一覧表示します
get_air_quality	最新のセンサー測定値を取得します（デバイス／場所／グループの選択に対応）
get_air_quality_history	指定した時間範囲内の履歴データを列指向 JSON として取得します
plot_air_quality_history	条件に一致するすべてのデバイスについて、センサーごとに履歴グラフを描画します
export_air_quality_history	条件に一致するデバイス全体から、1 つの履歴センサーを csv または xlsx ファイルにエクスポートします

すべてのツールは読み取り専用です。Cloud API はデバイスの設定や制御に対応していません。

インストール

pip install mcp-airq-cloud

または、ソースからインストールします。

git clone https://github.com/CorantGmbH/mcp-airq-cloud.git
cd mcp-airq-cloud
uv sync --frozen --extra dev

CLI の使用方法

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

mcp-airq-cloud list-devices
mcp-airq-cloud get-air-quality --device "Living Room"
mcp-airq-cloud get-air-quality-history --device "Living Room" --last-hours 24 --sensors co2 pm2_5
mcp-airq-cloud plot-air-quality-history --sensor co2 --output-format png --output co2.png
mcp-airq-cloud export-air-quality-history --sensor co2 --output-format xlsx --output co2.xlsx

履歴グラフとエクスポートの場合：

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

CLI のサブコマンド名は MCP ツール名と同じです。どちらの形式も使用できます。

mcp-airq-cloud list-devices
mcp-airq-cloud list_devices

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

mcp-airq-cloud serve

CLI はパイプでの使用に対応しています。コマンドが成功した場合の出力は stdout に、ツールエラーは終了コード 1 とともに stderr に出力されます。グラフ描画コマンドは stdout に直接ストリーミングすることもできます。

mcp-airq-cloud get-air-quality --device "Living Room" | jq '.co2'
mcp-airq-cloud get-air-quality-history --device "Living Room" --compact-json | jq '.columns.co2'
mcp-airq-cloud get-air-quality-history --device "Living Room" --yaml | yq '.columns.co2'
mcp-airq-cloud plot-air-quality-history --sensor co2 --device "Living Room" --output - > co2.png
mcp-airq-cloud export-air-quality-history --sensor co2 --device "Living Room" --output - > co2.xlsx

履歴データ

air-Q Cloud API 経由で履歴センサーデータにアクセスできるツールが 3 つあります。

グラフの描画

plot_air_quality_history は 1 つのセンサーのグラフを描画します。複数のデバイスが条件に一致する場合は、各デバイスが同じグラフ内の別々の系列になります。

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

1 つの場所にある複数デバイス（24 時間、エリアグラフ、PNG）

# Single device, last 24 hours (default), PNG output (default)
mcp-airq-cloud plot-air-quality-history --sensor co2 --device "Living Room"

# All devices at a location, custom time range, SVG output
mcp-airq-cloud 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-cloud plot-air-quality-history --sensor co2 --dark --chart-type line

# Save to file
mcp-airq-cloud 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-cloud export-air-quality-history --sensor co2 --device "Living Room" --last-hours 48

# Excel export for all devices at a location
mcp-airq-cloud export-air-quality-history --sensor co2 --location "Home" \
  --output-format xlsx --output co2.xlsx

共通パラメーター

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

設定

各デバイスの Cloud API key と 32 文字のデバイス ID が必要です。どちらも my.air-q.com で取得できます。

オプション 1：環境変数（インライン JSON）

export AIRQ_CLOUD_DEVICES='[{"id": "de45d2ed777780c96c0deae7a220b745", "api_key": "your-api-key", "name": "Living Room"}]'

オプション 2：デフォルトの設定ファイル（推奨）

JSON ファイルを ~/.config/airq-cloud-devices.json に配置します。環境変数は不要です。

[
  {"id": "de45d2ed777780c96c0deae7a220b745", "api_key": "your-api-key", "name": "Living Room"}
]

オプション 3：カスタム設定ファイルのパス

export AIRQ_CLOUD_CONFIG_FILE=/path/to/devices.json

オプション 4：グローバル API キー

すべてのデバイスで同じ API キーを共有する場合は、1 回だけ設定します。

export AIRQ_CLOUD_API_KEY="your-api-key"
export AIRQ_CLOUD_DEVICES='[{"id": "de45d2ed777780c96c0deae7a220b745", "name": "Living Room"}]'

デバイス設定のフィールド

フィールド	必須	説明
id	はい	32 文字のクラウドデバイス ID
api_key	いいえ	デバイスごとの API キー（AIRQ_CLOUD_API_KEY にフォールバックします）
name	いいえ	わかりやすい名前（デフォルトは ID の先頭 8 文字）
location	いいえ	グループ分けに使用する場所（例：「Wohnzimmer」）
group	いいえ	グループ分けに使用するグループ（例：「zu Hause」）

Claude Desktop での使用

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "air-Q Cloud": {
      "command": "mcp-airq-cloud",
      "env": {
        "AIRQ_CLOUD_DEVICES": "[{\"id\": \"<device-id>\", \"api_key\": \"<key>\", \"name\": \"Living Room\"}]"
      }
    }
  }
}

Claude Code での使用

claude mcp add air-Q-Cloud mcp-airq-cloud \
  -e AIRQ_CLOUD_DEVICES='[{"id":"<ID>","api_key":"<KEY>","name":"<Name>"}]'

開発

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

ライセンス

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