Buva Ecostream

An MCP (Model Context Protocol) server that connects Claude to a Buva EcoStream WTW ventilation unit over your local network.

Once installed, you can control your ventilation and read air quality data directly in conversation with Claude — no app needed.

Note: The EcoStream does not use a native WebSocket. It streams JSON state updates over a persistent HTTP long-poll connection. This server handles that automatically and falls back to polling if needed.

---

Features

• Read live sensor data: CO₂, TVOC, humidity, temperatures (ETA/EHA/ODA), fan RPM, bypass position, heat recovery efficiency, WiFi info
• Control fan presets (low / mid / high)
• Set a custom airflow in m³/h with optional duration
• Start/stop boost mode
• Open/close bypass valve
• Enable/disable schedule and summer comfort mode
• Reset filter timer
• Built-in endpoint discovery tool for diagnosing your specific device firmware

---

Requirements

• Python 3.11+
• Claude Desktop (or any MCP-compatible host)
• Buva EcoStream on your local network with a known IP address

---

Installation

1. Clone or download this repository

git clone https://github.com/YOUR_USERNAME/ecostream-mcp.git
cd ecostream-mcp

2. Install dependencies

pip3 install -r requirements.txt

3. Configure Claude Desktop

Open your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following (adjust the path and IP address):

{
  "mcpServers": {
    "ecostream": {
      "command": "python3",
      "args": ["/absolute/path/to/ecostream-mcp/server.py"],
      "env": {
        "ECOSTREAM_HOST": "192.168.X.X",
        "ECOSTREAM_PORT": "80",
        "ECOSTREAM_STREAM": "/stream",
        "ECOSTREAM_CONFIG": "/config"
      }
    }
  }
}

4. Restart Claude Desktop

The EcoStream tools will now appear automatically in Claude.

---

Configuration

All settings are passed as environment variables:

Variable	Default	Description
ECOSTREAM_HOST	192.168.1.100	IP address of your EcoStream
ECOSTREAM_PORT	80	HTTP port
ECOSTREAM_STREAM	/stream	Endpoint for reading state
ECOSTREAM_CONFIG	/config	Endpoint for sending commands

If you're unsure which endpoints your firmware uses, run the discover_endpoints tool in Claude after installation — it probes all known paths and shows which ones respond.

---

Available Tools

Tool	Description
get_status	Returns all current sensor values: CO₂, temperatures, airflow, fan speed, bypass, modes, WiFi
set_preset	Set ventilation to low, mid, or high preset
set_airflow	Set a custom airflow in m³/h with an optional duration in minutes
set_boost	Turn boost mode on or off (5, 10, 15, 30, or 60 minutes)
set_bypass	Open or close the bypass valve
set_schedule	Enable or disable the built-in ventilation schedule
set_summer_comfort	Enable or disable summer comfort mode (auto-bypass on warm days)
reset_filter	Reset the filter replacement timer after changing the filter
discover_endpoints	Scan the device for working HTTP endpoints — useful for initial setup or debugging

---

Example prompts

Once connected, you can ask Claude things like:

• "What's the CO₂ level right now?"
• "Turn on boost mode for 15 minutes, it's stuffy in here."
• "Set ventilation to low for the night."
• "Is the bypass open? What's the outside temperature?"
• "Reset the filter timer, I just replaced the filter."
• "Scan which endpoints the EcoStream responds to."

---

How it works

The EcoStream device exposes a local HTTP server. When polled, it returns JSON containing the full device state (sensor readings, active modes, setpoints). Configuration changes are sent as HTTP POST requests with a JSON body.

This server implements the MCP stdio transport, meaning Claude Desktop launches it as a subprocess and communicates over stdin/stdout.

State is fetched on demand when you call get_status. The server tries the configured streaming endpoint first, then falls back to /Status and /api/status if that fails.

For sending commands, the server tries the EcoStream JSON format ({"config": {...}}) and, if that doesn't respond, falls back to the older Q-Stream {"Value": "TIMER ..."} format.

---

Troubleshooting

"Cannot reach EcoStream"

• Confirm the device IP with your router's DHCP table
• Make sure your computer and the EcoStream are on the same network/VLAN
• Try curl http://192.168.x.x/Status in a terminal to test basic connectivity

Tools appear but return errors

• Run discover_endpoints in Claude to see which paths actually respond
• Adjust ECOSTREAM_STREAM and ECOSTREAM_CONFIG in your config accordingly

Sensor values are missing or labeled "unknown"

• Your firmware may use different JSON field names
• Run get_status and look at the "Overige velden" section — those are unrecognised fields from the device
• Open an issue with the raw output and I'll add support

---

Protocol notes

The reverse-engineered protocol is based on the community Home Assistant integration by @epodegrid and @Recognition2. This MCP server is an independent implementation and is not affiliated with BUVA.

Supported devices:

Device	Status
BUVA EcoStream	✅ Supported
BUVA EcoStream+	✅ Supported
BUVA Q-Stream 2.0	⚠️ Partial (different protocol, timer commands only)
Other BUVA models	❌ Not supported

---

License

MIT