aranet4

This MCP server provides a Python-based interface to manage Aranet4 CO2 sensors via MCP. It can scan for nearby Aranet4 devices, fetch and store data from the device into a local sqlite database, and answer queries about recent measurements or data from specific date ranges. It also supports generating plots for queried data when the client requests visualizations. Use the assisted configuration flow (init aranet4) to quickly configure your device and enable automatic data fetching. The server exposes tools for configuration, data fetching, and querying historical data, which can be invoked from an MCP client integrated with your workflow.

Prerequisites:

• Python 3.8+ (for running the Python server and dependencies)
• uv (via uvx) for MCP orchestration and isolated environments
• Access to a paired Aranet4 device over BLE

Installation steps:

1. Clone the repository:

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

2. Install the server dependencies (via uv/uvx environment or standard Python tooling):

   • Recommended (uv/uvx):

     • Ensure uv is installed: pipx install uv or follow uv's install instructions
     • Use the included pyproject.toml to manage dependencies when launching the server

   • Alternative (pip):

     • pip install .

3. Configure MCP client to run the server (example with uv):

   JSON snippet to include in MCP client config:

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

4. Run the MCP server via your MCP client or directly via UV if preferred. For manual startup, ensure your environment is prepared and the BLE device is paired.

5. Optional: Enable automatic data fetch by configuring a cron/launch agent as described in the repository's automatic data fetch section.

Notes:

• The server relies on a locally stored sqlite database to track measurements. Ensure write permissions to the database location.
• Use the assisted configuration flow (init aranet4) from the MCP client for a guided setup; fallback to manual edits in config.yaml if needed.
• If you need to reconfigure the device, you can re-run the init_aranet4_config tool or edit the configuration via get_configuration_and_db_stats/set_configuration utilities.
• For plotting data, request plots from your MCP client when querying get_recent_data or get_data_by_timerange to receive a visualization.
• If you encounter BLE discovery issues on macOS, ensure you have the necessary permissions and consider a BLE scanning utility or driver workaround as noted in the README.