Aranet4

What is aranet4-mcp-server?

aranet4-mcp-server is a simple MCP (Multi-Client Protocol) server designed to manage your Aranet4 CO2 sensor. It allows you to fetch data from the device, store it in a local SQLite database, and query historical data. It is built upon the Aranet4-Python library.

How to use aranet4-mcp-server?

1. Clone the repository: git clone git@github.com:diegobit/aranet4-mcp-server.git and navigate into the directory.
2. Prepare environment: Use uv (recommended) or pip install ..
3. Add to MCP client configuration: Configure your MCP client (e.g., Claude Desktop, Cursor) to run the src/server.py script, providing the correct path to uv and the project directory.
4. Configure: Use the AI-assisted configuration by asking init aranet4 in your client, or manually edit config.yaml with your device's MAC address and name.
5. Automatic Data Fetching: For continuous data updates, set up a cron job or a LaunchAgent (for macOS) to periodically run fetch-job.py.

Key Features of aranet4-mcp-server

• Device Scanning: Scan for nearby Aranet4 devices.
• Data Fetching & Storage: Fetch new data from the Aranet4 sensor and save it to a local SQLite database.
• Historical Data Querying: Ask questions about recent measurements or specific past dates.
• Data Visualization: (For MCP clients supporting images) Plot data for visual analysis.
• Assisted Configuration: Easy setup with AI-guided configuration.
• Configuration and Utils: Tools for initializing configuration, scanning devices, getting configuration and database stats, and setting configuration.
• Historical Data Update: fetch_new_data to update the local database.
• Historical Data Query: get_recent_data and get_data_by_timerange to retrieve data from the local database, with an option to generate plots.

Use Cases of aranet4-mcp-server

• Personal CO2 Monitoring: Track CO2 levels in your home or office over time.
• Environmental Data Logging: Create a historical record of CO2 data for analysis.
• Integration with MCP Clients: Seamlessly integrate Aranet4 data into your preferred MCP client for enhanced interaction and visualization.
• Automated Data Collection: Set up automated jobs to regularly collect CO2 data without manual intervention.

FAQ from aranet4-mcp-server

• How to get the standalone Python version without MCP logic? See aranet4-archiver.
• What is the recommended way to install dependencies? Using uv.
• Where can I find the configuration file for Claude Desktop or Cursor? For Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json; for Cursor (macOS): ~/.cursor/mcp.json.
• How can I get the MAC address of my Aranet4 device? Use aranetctl --scan from Aranet4-Python.
• How do I set up automatic data fetching on macOS? Copy com.diegobit.aranet4-fetch.plist to ~/Library/LaunchAgents/ and load it with launchctl load.
• Can I use Docker? Yes, a Dockerfile is available. Remember to pass environment variables or update config.yaml.

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.

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.