Aranet4 MCP Server

🚀 aranet4-mcp-server

An MCP server for managing Aranet4 carbon dioxide sensors, built on Aranet4-Python.

💡 Usage Tip

If you need a standalone Python version without MCP logic, check out aranet4-archiver.

✨ Features

• Scan nearby devices.
• Retrieve new data from the embedded device storage and save it to a local sqlite database for tracking and later viewing. See below for auto-updates.
• Query information on recent measurements or for specific past dates.
• [MCP clients supporting images] Request to display data as charts for a friendly visualization!
• Assistant configuration! 💫 After installation, simply enter init aranet4 in the client to set up the MCP server for use with your device.

📦 Installation

1. Clone the repository:

   git clone git@github.com:diegobit/aranet4-mcp-server.git
   cd aranet4-mcp-server
   

2. Prepare the environment:
   • Recommended (using uv): No action required. The provided pyproject.toml handles dependencies and virtual environments.
   • Alternative (using pip): Install with pip install ..
3. Add to the MCP client configuration:

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

   • Claude Desktop MacOS configuration file path: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Cursor MacOS configuration file path: ~/.cursor/mcp.json
4. Configuration:
   • Recommended (AI-assisted configuration!): Enter init aranet4 after starting the client for guided configuration.
   • Alternative (manual): Edit the file config.yaml. You need to provide the MAC address and device name. You can obtain the MAC address using aranetctl --scan from Aranet4-Python (installed as a dependency of this repository).

Dockerfile

A Dockerfile is provided. Please pass environment variables or update config.yaml.

🛠️ Tool List

Configuration and Tools

• init_aranet4_config: Assist with device configuration.
• scan_devices: Scan nearby Bluetooth Aranet4 devices.
• get_configuration_and_db_stats: Get general statistics of the current config.yaml and the local sqlite3 database.
• set_configuration: Set values in config.yaml.

Update Historical Data

• fetch_new_data: Retrieve new data from the configured nearby Aranet4 devices and save it to the local database.

Query Historical Data

• get_recent_data: Get recent data from the local database. You can specify how many measurements to retrieve.
• get_data_by_timerange: Get data from the local database within a specific time range. You can specify how many measurements to retrieve (note that if the time range is large and the limit is low, some data points may be skipped).

For both, you can request to generate and display a chart.

⏰ Task for Automatic Data Update

If you want the local database to always stay up-to-date, you can set up a cron job or a launch agent to automatically fetch data every few hours. On MacOS, follow these steps:

1. Configure the absolute paths in com.diegobit.aranet4-fetch.plist.
2. Install the LaunchAgent:

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

For other platforms, run fetch-job.py periodically in your preferred way.