Aqara Mcp Server

Aqara MCP Server は、Aqara Agent が提供するリモート MCP サービスです。MCP 対応の AI アプリケーションを Aqara のスマートホーム機能に安全に接続できます。MCP 統合が必要な場合は、Aqara Agent が提供するリモート MCP URL を設定してください。

ヒント

おすすめ：公式 Aqara Agent Skills

Codex App、Cursor、OpenClaw など、アプリケーションが Agent Skills に対応している場合は、まず公式の Aqara Agent Skills を使用することをおすすめします。MCP サーバーを設定しなくても、自然言語でホーム／スペース、デバイス、シーン、オートメーション、エネルギー消費量などを照会・操作できます。

• GitHub：aqara/aqara-agent-skills
• ClawHub：aqara/aqara-agent

目次

• 概要
• 機能
• 仕組み
• クイックスタート
  • 前提条件
  • ステップ 1：アカウント認証
  • ステップ 2：リモート MCP の設定
  • ステップ 3：確認
• 設定に関する注意事項
• MCP ツールリファレンス
  • コアツールの概要
  • ホームと位置
  • デバイスの照会と操作
  • シーン
  • オートメーション
  • エネルギー消費量
  • 照明効果
  • ファームウェア
  • パラメーターの規則
• ライセンス

概要

現在推奨される MCP 統合は、Aqara Agent を中心としています。

• リモート MCP：https://agent.aqara.com/open/mcp 経由の Streamable HTTP に対応するアプリケーション向けです。
• Aqara Agent Skills：Agent Skills に対応するアプリケーション向けです。MCP サーバーを手動で設定せずにスキルをインストールできます。
• MCP ツールの機能：ホーム／スペース、デバイス、シーン、オートメーション、エネルギー消費量、照明効果、ファームウェアに関するスマートホーム操作に対応しています。

機能

• 🔍 柔軟なデバイス照会：ホーム／スペース、デバイスタイプ、デバイス ID で、デバイスの基本情報、リアルタイムの状態、操作ログを照会できます。
• ✨ 包括的なデバイス操作：Aqara デバイスの電源、明るさ、色温度、温度、ファン速度、モード、カーテンの開閉率などを操作できます。
• 🎬 スマートシーン管理：シーンを照会・実行し、シーンの実行履歴を確認できます。
• ⏰ オートメーションの照会：オートメーションルールとその実行履歴を照会できます。
• 📈 エネルギー統計：部屋／スペースまたはデバイスごとに、集計表示と詳細表示で電力使用量とコストを照会できます。
• 💡 照明効果の管理：照明シナリオ／効果を照会し、指定した効果を適用し、効果の設定パラメーターを照会できます。
• 🔄 ファームウェア管理：現在および利用可能なファームウェアのバージョンを照会し、デバイスのファームウェア更新を開始できます。
• 🏠 複数のホームとスペース：Aqara アカウントに登録されたホームと、現在のホームの部屋／スペースを一覧表示できます。
• 🔌 リモート MCP 統合：Cursor や Codex App などのアプリから、MCP URL 経由で接続できます。
• 🔐 安全な認証：Aqara Agent にサインインすると aqara_api_key を取得できます。設定時には認証情報を安全に保管してください。

仕組み

リモート MCP モードでは、アプリケーションは HTTP 経由で Aqara Agent の MCP サービスに接続し、ログインページで生成されたベアラートークンを含めます。Aqara Agent は認証情報を検証し、ツール呼び出しを実行して、結果をアプリケーションに返します。

graph LR
    A[AI App / MCP host] --> B[Aqara Agent]
    B --> C[Aqara Cloud API]
    C --> D[Aqara Devices / Scenes / Automations]

1. AI アプリ／MCP ホスト：ユーザーは Cursor、Codex App などのアプリから自然言語で指示を送信します。
2. Aqara Agent：ユーザーの認証情報を検証し、内容を解釈して、対応するツールを実行します。
3. Aqara Cloud API：デバイス、シーン、自動化、エネルギー消費量、照明効果、ファームウェアなどのデータ照会や制御操作を実行します。

---

クイックスタート

前提条件

• スマートデバイスを登録済みの Aqara アカウント。
• Cursor や Codex App など、リモート MCP に対応したアプリケーション。
• Aqara Agent の認証情報：ログインページに表示される aqara_api_key と aqara_mcp_url。

ステップ 1：アカウント認証

1. ログインページを開きます： https://agent.aqara.com/login

2. サインインを完了します：

   • Aqara アカウントでサインインします。
   • サインイン後、ページに表示される aqara_api_key をコピーします。
   • MCP の設定には、ページに表示される aqara_mcp_url を使用します。通常は https://agent.aqara.com/open/mcp です。

3. 認証情報を安全に保管します：

   aqara_api_key は安全に保管してください。リポジトリにコミットしたり、スクリーンショットで公開したり、他の人と共有したりしないでください。

   

ステップ 2：リモート MCP の設定

Cursor

1. Cursor の設定を開き、Tools & MCPs に移動して、New MCP Server をクリックします。

   

2. リモート MCP の設定を追加します。ログインページに表示される aqara_mcp_url を使用してください。手動で入力する場合は、/open/mcp パスを使用します。

   {
     "mcpServers": {
       "aqara": {
         "type": "http",
         "url": "https://agent.aqara.com/open/mcp",
         "headers": {
           "Authorization": "Bearer <YOUR_AQARA_API_KEY>"
         }
       }
     }
   }
   

3. 設定を保存し、Cursor を再起動して MCP の設定を有効にします。

Codex App

1. ログインページに表示される aqara_api_key を環境変数として保存します。zsh を使用する macOS では、以下を ~/.zshrc に追加します。

   export AQARA_API_KEY="<YOUR_AQARA_API_KEY>"
   

2. Codex App を再起動し、設定からカスタム MCP に接続します。

3. Streamable HTTP を選択します。

4. ログインページに表示される aqara_mcp_url を入力します。例：https://agent.aqara.com/open/mcp。

5. Bearer token env var には API キーそのものではなく、環境変数名 AQARA_API_KEY を入力します。Codex App はこの変数からトークンを読み取ります。

ステップ 3：確認

設定が正常に完了したら、以下のような自然言語のリクエストでテストできます。

User: Show all devices in my home
Assistant: Query the device list via MCP

User: Turn on the living room light
Assistant: Run device control via MCP

User: Run the movie night scene
Assistant: Run the scene via MCP

アプリの MCP パネルに Aqara が接続済みとして表示され、Aqara のツールが表示されていれば、設定は有効です。

---

設定に関する注意事項

• MCP URL には https://agent.aqara.com/open/mcp またはログインページに表示される aqara_mcp_url を使用してください。ログインページの URL を MCP URL として使用しないでください。
• デバイス制御、シーン実行、ファームウェアのアップグレード用ツールは、実際のスマートホームデバイスに影響します。初回使用時は、まず照会ツールを実行して、ホーム、スペース、デバイス、シーンの情報を確認してください。
• 接続に失敗する場合は、MCP の種類が Streamable HTTP であること、URL に /open/mcp が含まれていること、認証情報の有効期限が切れていないこと、設定変更後にアプリを再起動したか、MCP を再読み込みしたことを確認してください。

---

MCP ツールリファレンス

以下のツール一覧は、現在の Aqara Agent サービスに登録されている関数定義に基づいています。アプリによって UI に表示されるツール名が異なる場合がありますが、パラメーターの意味と機能の範囲は同じです。

コアツールの概要

ツールカテゴリ	ツール	説明
ホームと位置	all_homes_inquiry, position_base_inquiry	ホームおよび部屋／スペースの情報を照会します
デバイスの照会と制御	device_base_inquiry, device_status_inquiry, device_status_control, fuzzy_device_batch_control, device_log_inquiry	デバイスの基本情報とリアルタイムの状態を照会し、デバイスを制御して、制御ログを表示します
シーン	scene_base_inquiry, scene_run, scene_execution_history_inquiry	シーンを照会・実行し、シーンの実行履歴を照会します
オートメーション	automation_base_inquiry, automation_execution_history_inquiry	オートメーションルールと実行履歴を照会します
エネルギー消費量	energy_consumption_inquiry_for_position, energy_consumption_inquiry_for_device	部屋／スペースまたはデバイスごとの電力使用量／コストを照会します
照明効果	lighting_effect_inquiry, device_lighting_effect_inquiry, lighting_effect_control, lighting_effect_config_params_inquiry	照明効果を照会・適用し、効果の構成パラメーターを照会します
ファームウェア	device_firmware_inquiry, device_firmware_upgrade	デバイスのファームウェアを照会・アップグレードします

ホームと位置

all_homes_inquiry

現在の Aqara アカウントに属するすべてのホームを照会します。

パラメーター： なし

戻り値： ホーム名、ホーム ID、および関連フィールドを含むホームのリストです。

position_base_inquiry

現在のホームにあるすべての部屋／スペースの基本情報を照会します。

パラメーター： なし

戻り値： 位置名、位置 ID、および関連フィールドを含む部屋／スペースのリストです。

デバイスの照会と制御

device_base_inquiry

リアルタイムの状態を含めず、部屋／スペースとデバイスタイプでデバイスの基本情報を照会します。

パラメーター：

• position_ids (Array<String>, optional): 部屋／スペース ID のリストです。空の場合、位置による絞り込みは適用されません。
• device_types (Array<String>, optional): デバイスタイプです。例：Light、Switch、Outlet、AirConditioner、WindowCovering、Camera。空の場合、デバイスタイプによる絞り込みは適用されません。

戻り値： デバイス名、デバイス ID、位置、デバイスタイプなどの基本情報を含むデバイスのリストです。

device_status_inquiry

電源、明るさ、色温度、温度、ファン速度、モードなどのデバイスのリアルタイム状態を照会します。

パラメーター：

• device_ids (Array<String>, optional): デバイス ID です。指定された場合、デバイス ID を優先して照会します。
• position_ids (Array<String>, optional): 部屋／スペース ID です。
• device_types (Array<String>, optional): デバイスタイプです。

戻り値： 現在取得可能な値を含むデバイス状態のリストです。

device_status_control

電源、明るさ、色温度、温度、ファン速度、モード、カーテンの開閉率など、指定したデバイスの状態や属性を制御します。

パラメーター：

• device_ids (Array<String>, required): 対象のデバイス ID です。
• attribute (String, required): 制御する属性です。例：on_off、brightness、color_temperature、temperature、percentage、mode。
• action (String, required): 制御アクションです。例：on、off、set、up、down、warmer、cooler、start、stop。
• value (String, optional): 目標値です。例：50、max、min、cool、heat、red。

戻り値： デバイス制御の実行結果です。

fuzzy_device_batch_control

部屋／スペースとデバイスタイプを指定してデバイスを一括制御します。たとえば、「すべての照明を消す」「リビングルームのすべてを消す」「すべてのエアコンを 26° に設定する」などの操作ができます。

パラメーター：

• position_ids (Array<String>, optional): 部屋／スペース ID です。空の場合、ホーム全体を意味することがあります。
• device_types (Array<String>, optional): デバイスタイプです。
• attribute (String, required): 制御する属性です。
• action (String, required): 制御アクションです。
• value (String, optional): 目標値です。

戻り値： 一括制御の実行結果です。

device_log_inquiry

期間を指定してデバイス制御ログを照会します。制御時刻、内容、結果が含まれます。

パラメーター：

• time_range (Array<String>, optional): 時間範囲。例：["2026-01-01 00:00:00", "2026-01-01 23:59:59"]。
• device_ids (Array<String>, optional): デバイス ID。指定した場合、デバイス ID を優先して照会します。
• position_ids (Array<String>, optional): 部屋／スペース ID。
• device_types (Array<String>, optional): デバイスの種類。

戻り値： 制御ログの一覧と、実際に照会された時間範囲。

シーン

scene_base_inquiry

シーン ID、position ID、またはデバイス ID で絞り込んで、シーンの基本情報を照会します。

パラメーター：

• scene_ids (Array<String>, optional): シーン ID。指定した場合、シーン ID を優先して照会します。
• position_ids (Array<String>, optional): 部屋／スペース ID。
• device_ids (Array<String>, optional): デバイスに関連するシーンのデバイス ID。

戻り値： シーンの基本情報の一覧。

scene_run

指定した 1 つ以上のシーンを実行します。

パラメーター：

• scene_ids (Array<String>, required): 実行するシーン ID。

戻り値： シーンの実行結果。

scene_execution_history_inquiry

期間を指定してシーンの実行履歴を照会します。

パラメーター：

• time_range (Array<String>, optional): 時間範囲。
• scene_ids (Array<String>, optional): シーン ID。
• position_ids (Array<String>, optional): 部屋／スペース ID。
• device_ids (Array<String>, optional): デバイス ID。

戻り値： シーンの実行履歴と、実際に照会された時間範囲。

オートメーション

automation_base_inquiry

オートメーション ID、position ID、またはデバイス ID で絞り込んで、オートメーションルールの基本情報を照会します。

パラメーター：

• automation_ids (Array<String>, optional): オートメーション ID。指定した場合、オートメーション ID を優先して照会します。
• position_ids (Array<String>, optional): 部屋／スペース ID。
• device_ids (Array<String>, optional): デバイスに関連するオートメーションのデバイス ID。

戻り値： オートメーションルールの一覧。

automation_execution_history_inquiry

期間を指定してオートメーションの実行履歴を照会します。

パラメーター：

• time_range (Array<String>, optional): 時間範囲。
• automation_ids (Array<String>, optional): オートメーション ID。
• position_ids (Array<String>, optional): 部屋／スペース ID。
• device_ids (Array<String>, optional): デバイス ID。

戻り値： オートメーションの実行履歴と、実際に照会された時間範囲。

エネルギー消費量

energy_consumption_inquiry_for_position

家／部屋／スペースごとの電力使用量または料金を、集計ビューと詳細ビューで照会します。

パラメーター：

• data_type (String, required): 照会するデータの種類。1 は電力使用量、2 は電気料金、3 は両方です。
• time_range (Array<String>, required): 時間範囲。
• time_gradient (String, optional): 集計間隔：30min、1hour、1day、1week、1month。
• data_aggregation_mode (String, optional): total = 集計サマリー、detail = 詳細ビュー。
• positions (Array<String>, optional): 部屋／スペース ID。空の場合、有効な部屋をすべて照会します。

戻り値： 部屋／スペースごとの電力使用量／料金の統計情報。

energy_consumption_inquiry_for_device

位置またはデバイスで絞り込んで、デバイスごとの電力使用量または料金を集計ビューと詳細ビューで照会します。

パラメーター：

• data_type (String, required): 1 = 電力使用量、2 = 電気料金、3 = 両方。
• time_range (Array<String>, required): 時間範囲。
• time_gradient (String, optional): 30min、1hour、1day、1week、1month。
• data_aggregation_mode (String, optional): total = 集計サマリー、detail = 詳細ビュー。
• positions (Array<String>, optional): 部屋／スペース ID。
• device_ids (Array<String>, optional): デバイス ID。指定した場合、デバイスを優先して照会します。

戻り値： デバイスごとの電力使用量／料金の統計情報。

照明効果

lighting_effect_inquiry

家で利用可能な照明シーン／エフェクトを照会します。

パラメーター： なし

戻り値： エフェクト名と、制御に適用可能な範囲の一覧。

device_lighting_effect_inquiry

デバイスごとに対応している照明エフェクト名を照会します。

パラメーター：

• device_ids (Array<String>, required): エフェクトを照会するデバイス ID。

戻り値： デバイスとエフェクト名の対応一覧。

lighting_effect_control

指定した照明エフェクトを対象のデバイスまたは部屋／スペースに適用します。

パラメーター：

• effect_name (String, required): エフェクト名。
• device_ids (Array<String>, optional): 対象のデバイス ID。指定した場合、デバイスへの制御が優先されます。
• position_ids (Array<String>, optional): 部屋／スペース ID。

戻り値： 照明エフェクト制御の実行結果。

lighting_effect_config_params_inquiry

照明デバイスで照明エフェクトを設定するために必要なパラメーターを照会します。

パラメーター：

• device_ids (Array<String>, required): 対象の照明デバイス ID。

戻り値： 設定可能な項目、値の範囲、保存済みのユーザーエフェクトなど、エフェクトの設定パラメーター。

ファームウェア

device_firmware_inquiry

デバイスの現在のファームウェアバージョンと、利用可能なアップグレードバージョンを一括で照会します。

パラメーター：

• device_ids (Array<String>, optional): デバイス ID。指定した場合、デバイスへの照会が優先されます。
• position_ids (Array<String>, optional): 部屋／スペース ID。
• device_types (Array<String>, optional): デバイスの種類。

戻り値： デバイス名、オンライン状態、現在のバージョン、利用可能なバージョンなどのファームウェア情報。

device_firmware_upgrade

デバイス、場所、または種類で絞り込んだ後、対象デバイスのファームウェアアップグレードを開始します。

パラメーター：

• device_ids (Array<String>, optional): デバイス ID。指定した場合、これらのデバイスのアップグレードが優先されます。
• position_ids (Array<String>, optional): 部屋／スペース ID。
• device_types (Array<String>, optional): デバイスの種類。

戻り値： ファームウェアアップグレードの送信結果。

パラメーターの規則

• position_ids / positions：部屋／スペース ID の一覧です。省略した場合、照会または制御の範囲は各ツールの説明に従います。
• device_ids：デバイス ID またはデバイスエンドポイント ID の一覧です。クライアント側での識別とサーバーのマッピングを通じて解決されます。
• device_types：デバイスの種類です。例：Light、Switch、Outlet、AirConditioner、WindowCovering、Camera、TemperatureSensor。
• attribute：制御属性です。例：on_off、brightness、color_temperature、temperature、wind_speed、mode、percentage、volume、color。
• action：制御アクションです。例：on、off、set、up、down、warmer、cooler、start、stop、pause、resume。
• value：目標値です。例：50、100、max、min、red、cool、heat、照明エフェクト名。
• time_range：時間範囲の配列です。通常は ["YYYY-MM-DD HH:MM:SS", "YYYY-MM-DD HH:MM:SS"] です。
• data_type：エネルギーの照会タイプです。1 = 電力使用量、2 = 電気料金、3 = 両方。
• time_gradient：エネルギー統計の粒度です：30min、1hour、1day、1week、1month。
• data_aggregation_mode：エネルギーの集計モードです。total = 集計サマリー、detail = 詳細表示。

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については LICENSE ファイルをご覧ください。

---

Copyright © 2025 Aqara-Agent. All rights reserved.