aranet4-mcp-server

aranet4-mcp-server

用于管理 Aranet4 CO2 传感器的 MCP 服务。基于 Aranet4-Python 构建。

提示

如需不包含 MCP 逻辑的独立 Python 版本，请参阅 aranet4-archiver。

功能：

• 扫描附近的设备。
• 从设备内置存储中获取新数据，并保存到本地 sqlite 数据库，以便跟踪和日后查看。有关自动更新，请参阅下文。
• 询问近期测量数据或某个特定日期的历史数据。
• [适用于支持图片的 MCP 客户端] 请求将数据绘制成图表，以便直观查看！
• 辅助配置！ 💫 安装后，只需在客户端中询问 init aranet4，即可完成所有设置，让 MCP 服务与设备配合工作。

要求

已配对的 Aranet4 设备。设备使用 BLE，因此不会出现在常规蓝牙搜索中。在 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 地址和设备名称。可以通过 Aranet4-Python 中的 aranetctl --scan 获取 MAC 地址（该工具随本仓库依赖项一起安装）。

Dockerfile

提供了 Dockerfile。请记得传入环境变量或更新 config.yaml。

工具列表

配置和实用工具：

• init_aranet4_config：辅助配置设备。
• scan_devices：扫描附近的蓝牙 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 timer（Linux）或 cronjob，让它每隔几小时自动获取数据。

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
   

   获取任务会在激活时运行一次，此后每 3 小时运行一次，并补跑机器关闭期间错过的任务。若要在没有打开的登录会话时保持运行，请使用 loginctl enable-linger $USER 启用 linger。

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