Matterbridge MelCloud Plugin

A Matterbridge plugin to control Mitsubishi air conditioning units via MelCloud in Matter-compatible smart home ecosystems.

Features

• On/Off Control: Turn your air conditioning on or off
• Temperature Control: Set target temperature
• Mode Selection: Switch between heating, cooling, auto, fan, and dry modes
• Real-time Status: Automatic polling of device state
• Multi-device Support: Discovers and exposes all Air-to-Air devices from your MelCloud account

Requirements

• Matterbridge >= 3.4.0
• A MelCloud account with registered Mitsubishi air conditioning units
• Node.js >= 20.19.0

Installation

npm install matterbridge-melcloud

Or install via the Matterbridge frontend.

Configuration

Configure the plugin in the Matterbridge frontend or edit the config file directly:

{
  "name": "matterbridge-melcloud",
  "type": "DynamicPlatform",
  "username": "[email protected]",
  "password": "your-melcloud-password",
  "pollingInterval": 30000,
  "whiteList": [],
  "blackList": [],
  "debug": false
}

Configuration Options

| Option | Type | Default | Description | | ----------------- | ------- | ---------- | ----------------------------------- | | username | string | required | Your MelCloud account email | | password | string | required | Your MelCloud account password | | pollingInterval | number | 30000 | How often to poll device state (ms) | | whiteList | array | [] | Only expose devices in this list | | blackList | array | [] | Exclude devices in this list | | debug | boolean | false | Enable debug logging |

Supported Devices

Currently supports Air-to-Air (DeviceType 0) Mitsubishi units connected via MelCloud.

Matter Thermostat Modes

The plugin maps MelCloud modes to Matter thermostat modes:

| MelCloud Mode | Matter Mode | | ------------- | ----------- | | Heating | Heat | | Cooling | Cool | | Auto | Auto | | Fan | Fan Only | | Dry | Dry | | Off | Off |

Available workflows

The project has the following already configured workflows:

• build.yml: run on push and pull request and build, lint and test the plugin on node 20, 22 and 24 with ubuntu, macOS and windows.
• publish.yml: publish on npm under tag latest when you create a new release in GitHub and publish under tag dev on npm from main (or dev if it exist) branch every day at midnight UTC if there is a new commit. The workflow has been updated for trusted publishing / OIDC, so you need to setup the package npm settings to allow it (i.e. authorize publish.yml).
• codeql.yml: run CodeQL from the main branch on each push and pull request.
• codecov.yml: run CodeCov from the main branch on each push and pull request. You need a codecov account and to add your CODECOV_TOKEN to the repository secrets.

⚠️ Warning: GitHub Actions Costs for Private Repositories

Important: If you plan to use this template in a private repository, be aware that GitHub Actions usage may incur costs:

• Free tier limits: Private repositories have limited free GitHub Actions minutes per month (2,000 minutes for free accounts).
• Workflow intensity: This template includes multiple workflows that run on different operating systems (Ubuntu, macOS, Windows) and Node.js versions (20, 22, 24), which can consume minutes quickly.
• Daily automated workflows: The dev publishing workflows run daily, which can add up over time.
• Pricing varies by OS: macOS runners cost 10x more than Ubuntu runners, Windows runners cost 2x more.

Recommendations for private repos:

• Monitor your GitHub Actions usage in your account settings.
• Consider disabling some workflows or reducing the OS/Node.js version matrix.
• Review GitHub's pricing for Actions to understand costs.
• For public repositories, GitHub Actions are free with generous limits.

Getting Started

1. Create a repository from this template using the template feature of GitHub.
2. Clone it locally and open the cloned folder project with VS Code. If you have docker or docker desktop, just run code ..
3. When prompted, reopen in the devcontainer. VS Code will automatically build and start the development environment with all dependencies installed.
4. Update the code and configuration files as needed for your plugin. Change the name (keep always matterbridge- at the beginning of the name), version, description, author, homepage, repository, bugs and funding in the package.json.
5. Follow the instructions in the matterbridge README-DEV and comments in module.ts to implement your plugin logic.

Using the Dev Container

• Docker Desktop or Docker Engine are required to use the Dev Container.
• Devcontainer works correctly on Linux, macOS, Windows, WSL2.
• The devcontainer provides Node.js, npm, TypeScript, ESLint, Prettier, Jest, Vitest and other tools and extensions pre-installed and configured.
• The dev branch of Matterbridge is already build and installed into the Dev Container and linked to the plugin. The plugin is automatically added to matterbridge.
• The devcontainer is optimized using named mounts for node_modules, .cache and matterbridge.
• You can run, build, and test your plugin directly inside the container.
• To open a terminal in the devcontainer, use the VS Code terminal after the container starts.
• All commands (npm, tsc, matterbridge etc.) will run inside the container environment.
• All the source files are on the host.

Dev containers networking limitations

Dev containers have networking limitations depending on the host OS and Docker setup.

• Docker Desktop on Windows or macOS:

• Runs inside a VM

• Host networking mode is NOT available

• Use the Matterbridge Plugin Dev Container system (https://matterbridge.io/reflector/MatterbridgeDevContainer.html) for development and testing. It provides a similar environment to the native Linux setup with the following features:

  ✅ Is possible to pair with an Home Assistant instance running in docker compose on the same host

  ✅ mDNS works normally inside the containers

  ✅ Remote and local network access (cloud services, internet APIs) work normally

  ✅ Matterbridge and plugins work normally

  ✅ Matterbridge frontend works normally

• Use the Matterbridge mDNS Reflector with the Matterbridge Plugin Dev Container system (https://matterbridge.io/reflector/Reflector.html) if you want to pair with a controller on the local network with the following features:

  ✅ Is possible to pair with a controller running on the local network using mDNS reflector

  ✅ mDNS, remote and local network access (cloud services, internet APIs) work normally

  ✅ Matterbridge and plugins work normally

  ✅ Matterbridge frontend works normally

• Native Linux or WSL 2 with Docker Engine CLI integration:

• ✅ Host networking IS available (with --network=host)

• ✅ Full local network access is supported

• ✅ Matterbridge and plugins work correctly, including pairing

• ✅ Matterbridge frontend works normally

Documentation

Refer to the Matterbridge documentation for other guidelines.