heatpump-mcp

Voice control for a Fujitsu heat pump through the FGLair cloud, as an MCP server and a claude-voice plugin.

You ask "how warm is it in the living room?", and the voice reads the answer from the heat pump: whether it is on, what it is doing, the temperature it is set to, the room and outdoor temperatures, and the fan.

Try it without a heat pump

The pretend unit touches no network, and every answer says it is simulated:

$ uv run heatpump-mcp status --simulate
Simulated: The heat pump is on, heating to 21 degrees. The room is 20.5 degrees, and it is 3 degrees outside. The fan is on auto.

The same tools are served to a voice session over stdio, and the server stops when its input closes:

$ uv run heatpump-mcp serve --simulate < /dev/null

Related MCP server: mcp-server-tuya

The real heat pump

The real unit is reached through Fujitsu's FGLair cloud, the same way Home Assistant's built-in FGLair integration reaches it (ADR-HM-001). It needs the login of the FGLair app, in two files that only the owner can read:

mkdir -p ~/.config/heatpump-mcp && cd ~/.config/heatpump-mcp
printf '%s' 'the-email-you-sign-in-with' > fglair-username
printf '%s' 'your-fglair-password' > fglair-password
chmod 600 fglair-username fglair-password

An optional config.toml beside them holds region (eu, the default; default for the Americas and elsewhere; or cn) and unit, the unit's name in the FGLair app, which is needed only when the account has more than one. A file anyone else can read is refused.

Until the login is there, the server still starts, and every answer says what to set up:

$ uv run heatpump-mcp status --config-dir /nonexistent
The heat pump's login is not set up: Write the FGLair login to /nonexistent/fglair-username, one value per file, then chmod 600 it.

With the login in place, uv run heatpump-mcp serve serves the real unit, and uv run heatpump-mcp status reads it once.

The tools

Every answer has say, a sentence to read aloud as it is, and success, which a program can read. After a change, success is true only when the unit, read back, shows it; otherwise say tells the owner it is not confirmed.

The safety rules

• Nothing changes without a question and a spoken yes. A token works for the most recent question only, once, for 30 seconds; a wrong one cancels the question.

• Temperatures from 16 to 28 °C only; anything else is refused.

• At most one change every 10 seconds.

• Only power, mode, temperature and fan. Nothing in the code touches the unit's firmware, Wi-Fi, schedules, timers or the cloud account, and a test refuses any code that so much as names them.

• A change that never reached the unit can be confirmed again with the same token while it is fresh; nothing is retried on the plugin's own initiative.

The gates

Every one of these runs in continuous integration, and all of them run here:

$ uv run ruff check .
All checks passed!

uv run ruff format --check .   # layout
uv run mypy src                # types
uv run pytest -q               # behaviour
python scripts/mutate.py       # that each rule's own test can fail

CONTRIBUTING.md says what each one is for, and decisions/ records the choices that shaped them, including how a change is made here.

Licence

GPL-3.0-or-later. See LICENSE.