aranet4-mcp-server

aranet4-mcp-server

Aranet4 CO2 センサーを管理する MCP サーバーです。Aranet4-Python を基に構築されています。

ヒント

MCP のロジックを含まない単独の Python 版については、aranet4-archiver をご覧ください。

機能：

• 近くにあるデバイスをスキャンします。
• デバイス内蔵メモリから新しいデータを取得し、追跡や後からの閲覧に使えるようローカルの sqlite データベースに保存します。自動更新については、ページ下部をご覧ください。
• 最近の測定値や特定の過去の日付について質問できます。
• [画像に対応した MCP クライアント向け] データをプロットして、見やすく可視化できます！
• 設定をサポート！ 💫 インストール後、クライアントで init aranet4 と尋ねるだけで、MCP サーバーがデバイスと連携するための設定をすべて行えます。

必要条件

ペアリング済みの Aranet4 デバイスが必要です。デバイスは BLE を使用するため、通常の Bluetooth 検索には表示されません。MacOS では、App Store から LightBlue をインストールする方法があります。

インストール

1. リポジトリをクローンします：

   git clone [email protected]:diegobit/aranet4-mcp-server.git`
   cd aranet4-mcp-server
   

2. 環境を準備します：

   • 推奨（uv を使用）：特に必要な作業はありません。付属の pyproject.toml が依存関係と仮想環境を管理します。
   • 代替方法（pip を使用）：pip install . でインストールします。

3. MCP クライアントの設定に追加します：

   "aranet4": {
     "command": "{{PATH_TO_UV}}", // run `which uv`
       "args": [
         "--directory",
         "{{PATH_TO_SRC}}/aranet4-mcp-server/",
         "run",
         "src/server.py"
       ]
   }
   

   • Claude Desktop の MacOS 設定ファイルのパス：~/Library/Application Support/Claude/claude_desktop_config.json
   • Cursor の MacOS 設定ファイルのパス：~/.cursor/mcp.json

4. 設定します：

   • 推奨（AI による設定サポート！）：クライアントを起動し、init aranet4 と尋ねると、ガイドに沿って設定できます。
   • 代替方法（手動）：config.yaml ファイルを編集します。MAC アドレスとデバイス名を指定する必要があります。MAC アドレスは、Aranet4-Python の aranetctl --scan で取得できます（このリポジトリの依存関係とともにインストールされます）。

Dockerfile

Dockerfile を利用できます。環境変数を渡すか、config.yaml を更新してください。

ツール一覧

設定とユーティリティ：

• init_aranet4_config：デバイスの設定をサポートします。
• scan_devices：近くにある Bluetooth 対応の aranet4 デバイスをスキャンします。
• get_configuration_and_db_stats：現在の config.yaml と、ローカルの sqlite3 データベースの全般的な統計情報を取得します。
• set_configuration：config.yaml の値を設定します。

過去のデータを更新する場合：

• fetch_new_data：近くにある設定済みの aranet4 デバイスから新しいデータを取得し、ローカルデータベースに保存します。

過去のデータを照会する場合：

• get_recent_data：ローカルデータベースから最近のデータを取得します。測定値の数を指定できます。
• get_data_by_timerange：ローカルデータベースから特定の期間のデータを取得します。測定値の数を指定できます（期間が長く、上限値が小さい場合、データポイントが抜けることがあるため注意してください）。

どちらの場合も、プロットを依頼すると生成して表示できます。

データの自動取得ジョブ

ローカルデータベースを常に最新の状態に保つには、数時間ごとにデータを自動取得する launch agent（macOS）、systemd タイマー（Linux）、または cron ジョブを設定できます。

macOS（launchd）

1. com.diegobit.aranet4-fetch.plist に絶対パスを設定します。
2. LaunchAgent をインストールします：

   cp com.diegobit.aranet4-fetch.plist ~/Library/LaunchAgents/
   launchctl load ~/Library/LaunchAgents/com.diegobit.aranet4-fetch.plist
   

Linux（systemd ユーザータイマー）

1. systemd/aranet4-fetch.service に絶対パスを設定します。
2. タイマーをインストールして有効化します：

   mkdir -p ~/.config/systemd/user
   cp systemd/aranet4-fetch.service systemd/aranet4-fetch.timer ~/.config/systemd/user/
   systemctl --user daemon-reload
   systemctl --user enable --now aranet4-fetch.timer
   

   取得処理は有効化時に 1 回実行され、その後は 3 時間ごとに実行されます。マシンの電源がオフの間に実行されなかった分も補完されます。ログインセッションを開いていない状態でも実行を続けるには、loginctl enable-linger $USER で lingering を有効にします。

Linux（cron）

または、crontab（crontab -e）に次の行を追加します：

0 */3 * * * cd /home/diego/code/aranet4-mcp-server && /home/diego/.local/share/mise/shims/uv run fetch-job.py