Aranet4 MCP Server

What is Aranet4 MCP Server about?

Aranet4 MCP Server provides a lightweight backend for interacting with an Aranet4 CO2 sensor. It discovers nearby BLE devices, pulls historical measurements from the sensor's memory, persists them locally, and makes the data queryable and plottable via MCP‑compatible clients.

How to use Aranet4 MCP Server?

1. Clone the repository and enter the project directory.
2. Set up the environment – the recommended way is to use uv (or pip install . as an alternative).
3. Configure the server either by running init aranet4 in your MCP client for AI‑assisted setup or by editing config.yaml manually with the device MAC address and name.
4. Add the server to your MCP client configuration using the provided JSON snippet (path to uv and arguments to run src/server.py).
5. Start the server (e.g., uv run src/server.py).
6. (Optional) Deploy with Docker using the supplied Dockerfile.

Key features of Aranet4 MCP Server

• Scan for nearby Aranet4 devices over BLE.
• Fetch new data from the sensor’s internal memory and append it to a local SQLite database.
• Query recent measurements or data within a specific time range.
• Generate plots for visual inspection (supported by MCP clients that handle images).
• AI‑assisted configuration via the init aranet4 command.
• Command‑line utilities for configuration, scanning, fetching, and statistics.
• Docker support for containerized deployment.
• Simple cron/launch‑agent setup for automatic periodic data collection.

Use cases of Aranet4 MCP Server

• Home or office indoor air‑quality monitoring with long‑term CO2 trend analysis.
• Integration into automation workflows that need periodic sensor readings.
• Providing visual charts to end‑users through MCP‑enabled assistants like Claude or Cursor.
• Lightweight, self‑hosted data logging without relying on external cloud services.

FAQ from the Aranet4 MCP Server

Q: Do I need the Aranet4 already paired on my machine? A: Yes. The sensor must be paired once via BLE (e.g., using LightBlue on macOS) before the server can communicate with it.

Q: Can I run the server on Windows? A: The code is cross‑platform Python, but BLE scanning may require additional drivers. macOS is the primary tested environment.

Q: How does automatic data fetching work? A: Place fetch-job.py in a scheduled task (cron, launch agent, etc.) or use the provided com.diegobit.aranet4-fetch.plist on macOS to run the fetch routine at regular intervals.

Q: Do I need Docker? A: Docker is optional; it simplifies deployment but the server can run directly from a Python environment.

Q: Where is the data stored? A: All measurements are saved in a local SQLite database file located in the project directory.

aranet4-mcp-server

MCP server to manage your Aranet4 CO2 sensor. Built upon Aranet4-Python.

[!TIP] For the standalone python version without MCP logic, see aranet4-archiver.

Features:

• Scan for nearby devices.
• Fetch new data from embedded device memory and save to a local sqlite db for tracking and later viewing. For automatic updates, see at the bottom.
• Ask questions about recent measurements or about a specific past date.
• [For MCP clients that support images] Ask data to be plotted to also have a nice visualization!
• Assisted configuration! 💫 After installation, just ask init aranet4 in your client to set up everything for the mcp server to work with your device.

Requirements

An Aranet4 device already paired. The device uses BLE, so it won't be shown in regular bluetooth search. On MacOS, one way is to install LightBlue from the App Store.

Installation

1. Clone repo:

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

2. Prepare environment:

   • Recommended (with uv): Nothing to do. The provided pyproject.toml handles dependencied and virtual environments.
   • Alternative (with pip): install with pip install .

3. Add to 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 config file path: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Cursor MacOS config file path: ~/.cursor/mcp.json

4. Configure:

   • Recommended (AI assisted config!): start your client and ask init aranet4 to get a guided configuration.
   • Alternative (manual): edit file config.yaml. You need to provide the mac address and the device name. You can get the mac address with aranetctl --scan from Aranet4-Python (installed with this repo dependencies).

Dockerfile

Dockerfile is available. Remember to pass env variables or update config.yaml.

List of tools

Configuration and utils:

• init_aranet4_config: assisted configuration of device.
• scan_devices: scan nearby bluetooth aranet4 devices.
• get_configuration_and_db_stats: get current config.yaml and general stats from the local sqlite3 db.
• set_configuration: set values in config.yaml.

To update historical data:

• fetch_new_data: fetch new data from configured nearby aranet4 device and save to local db.

To query historical data:

• get_recent_data: get recent data from local db. Can specify how many measurements.

• get_data_by_timerange: get data in specific timerange from local db. Can specify how many measurements (careful, if the range is big and the limit is low, datapoints will be skipped).

  For both, ask to receive a plot to have it generated and displayed.

Automatic data fetch job

If you want your local db to always be updated, you can setup a cronjob or a launch agent that fetches data automatically every few hours. In MacOS, do as follows:

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

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

For other platforms, just run fetch-job.py periodically however you prefer.