AR
Database

Aranet4 MCP Server for CO2 Data Logging

Manage Aranet4 CO2 data with an MCP server: fetch sensor readings, store locally in SQLite, and query historical data for analysis.

View on GitHub
Quick Install
npx -y @diegobit/aranet4-mcp-server

Overview

Aranet4 MCP Server provides a lightweight MCP (Model Context Protocol) server to collect, store and query CO2 measurements from an Aranet4 sensor. It uses the Aranet4-Python library to communicate with the BLE sensor, pulls historical measurements from the device memory, and persists readings into a local SQLite database for offline analysis and visualization.

This server is designed to be run as an MCP tool inside an MCP-capable client (for example Claude Desktop or Cursor) or as a standalone service. It supports interactive setup, scheduled data fetching, and query endpoints that return recent or time-range data. Clients that support images can request plotted visuals of the measurements.

Features

  • Scan and discover nearby Aranet4 BLE devices.
  • Pull historical and new measurements from Aranet4 device memory.
  • Persist readings to a local SQLite database (configurable path).
  • Query recent measurements or arbitrary time ranges.
  • Generate plots (images) for clients that support inline images.
  • Assisted setup: run init aranet4 from an MCP client to walk through configuration.
  • Optional automatic data fetching via cron, launch agent, or provided fetch job script.
  • Dockerfile available for containerized deployment.

Installation / Configuration

  1. Clone the repository:
git clone [email protected]:diegobit/aranet4-mcp-server.git
cd aranet4-mcp-server
  1. Install dependencies

Recommended: use the provided pyproject.toml and run with uv (Astral) which handles virtualenvs:

# run the server with uv (Astral)
which uv        # find uv executable for MCP client config
uv --directory /path/to/aranet4-mcp-server run src/server.py

Alternative: install with pip

pip install .
  1. Add to your MCP client configuration (example JSON):
"aranet4": {
  "command": "/usr/local/bin/uv",
  "args": [
    "--directory",
    "/path/to/aranet4-mcp-server/",
    "run",
    "src/server.py"
  ]
}

Paths shown above must be absolute for MCP clients. Example configuration files:

  • Claude Desktop macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Cursor macOS: ~/.cursor/mcp.json
  1. Configure device and database
  • Recommended (AI-assisted): open your MCP client and ask: init aranet4 — this guides you through setting the device MAC address, device name and DB path.
  • Manual: edit config.yaml in the repository to set the Aranet4 MAC address, device name and SQLite DB path. You can discover your device MAC with the included scan tool (see Tools section) or with aranetctl --scan from Aranet4-Python.
  1. Optional: Docker

A Dockerfile is included. If using Docker, pass environment variables or mount a config.yaml and volume for the SQLite DB.

Available Tools / Resources

The server exposes a set of MCP tools and helper scripts for configuration, fetching and querying:

Tool / ScriptPurpose
init_aranet4_configGuided configuration wizard (AI-assisted via MCP).
scan_devicesScan for nearby Aranet4 BLE devices and report MAC + name.
set_configurationModify entries in config.yaml programmatically.
get_configuration_and_db_statsReturn current config and basic DB statistics.
fetch_new_dataRetrieve new measurements from the device and insert into SQLite DB.
get_recent_dataReturn the most recent N measurements from the DB.
get_data_by_timerangeQuery measurements between two timestamps (with optional sampling limit).
fetch-job.pyScript useful for scheduled fetch runs (used by cron/launchd).

Data is stored in a local SQLite database whose path is set in config.yaml. Plot generation uses matplotlib (or similar) to produce image outputs for clients that support images.

Use Cases

  • Periodic logging: Run fetch_new_data on a schedule (cron, systemd timer, or macOS LaunchAgent) to keep a rolling local history of CO2, temperature and humidity. Example LaunchAgent install (macOS):
cp com.diegobit.aranet4-fetch.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.diegobit.aranet4-fetch.plist
  • Ad-hoc queries: From your MCP client ask the server for recent readings:

Example prompt (MCP client):

  • “get_recent_data limit=50” — returns the most recent 50 rows.

  • “get_data_by_timerange start=2026-03-01T00:00 end=2026-03-07T23:59 limit=500” — returns data in the specified range (the limit parameter can be used to sample/skip rows if range is large).

  • Visualization: Request a plotted view of the last N measurements. If your MCP client supports images, the server can return a PNG plot showing CO2, temperature and humidity trends over time.

  • Diagnostics and setup: Use scan_devices to discover a paired Aranet4 and then run init_aranet4_config to populate config.yaml, avoiding manual edits.

Notes and Best Practices

  • BLE visibility: Aranet4 uses BLE and may not appear in standard system Bluetooth lists. Use the scanning tool or LightBlue (macOS) to discover the sensor.
  • DB retention: SQLite storage is local — set up regular backups if you depend on long-term retention.
  • Automation: For reliable data collection, schedule fetch_new_data to run every few hours. When running in containers, mount the DB file to persistent storage.

Repository and source code: https://github.com/diegobit/aranet4-mcp-server

If you are new to Aranet4-Python or BLE tooling, start with a manual scan and the assisted init aranet4 flow to ensure the server can reach your device before enabling automatic jobs.

Tags:database