unofficialMCP4Vaillant

An unofficial MCP (Model Context Protocol) server that exposes a Vaillant heat pump's data to AI assistants like Claude. Query outdoor and room temperatures, hot water status, energy consumption, COP estimates, schedules, and diagnostics through natural conversation.

This project is not affiliated with, endorsed by, or sponsored by Vaillant Group. "Vaillant" is a registered trademark of Vaillant Group; it is used here only to describe what the server connects to.

Disclaimer: This project uses an unofficial, reverse-engineered API via myPyllant and is not affiliated with Vaillant Group. The API may change or break at any time. Use at your own risk.

Features (v1, read-only)

• Status snapshot — outdoor / room / DHW temperatures, water pressure, per-zone setpoints, per-circuit flow temperature, special functions.

• Hardware inventory — controller, firmware, all heat generators and auxiliary devices, serial numbers.

• Energy report — consumption, environment energy, heat generated per device per operation mode, with a derived COP estimate and quality flag.

• Diagnostics — trouble codes, heating curve, bivalence points, holiday mode.

Write/control operations are explicitly out of scope for v1.

Related MCP server: zont-mcp

Prerequisites

• A MyVaillant account with at least one claimed system.

• Python 3.10–3.13 (myPyllant does not yet support 3.14).

• Claude Desktop or any MCP-compatible client.

Installation

git clone https://github.com/holger1411/unofficialMCP4Vaillant.git
cd unofficialMCP4Vaillant
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e .

Configuration

cp .env.example .env
# edit .env and set VAILLANT_USERNAME, VAILLANT_PASSWORD,
# and (if not in Germany or not the Vaillant brand) VAILLANT_BRAND / VAILLANT_COUNTRY.

Claude Desktop

Add to your claude_desktop_config.json (see claude_desktop_config_snippet.json for a template):

{
  "mcpServers": {
    "unofficial-mcp4vaillant": {
      "command": "/absolute/path/to/unofficialMCP4Vaillant/.venv/bin/python",
      "args": ["-m", "vaillant_mcp_server"],
      "env": {
        "VAILLANT_USERNAME": "your-email@example.com",
        "VAILLANT_PASSWORD": "your-password"
      }
    }
  }
}

Available Tools

Time ranges accepted: today, yesterday, week (ISO Mon–today), month, year, custom. All ranges are resolved in the home's local timezone, not the host's.

Architecture

• Single long-lived MyPyllantAPI instance, owned by a VaillantClient. Concurrent reads are lock-free; the lock is held only during initial login and re-login.

• On 401/403, the client transparently re-authenticates and retries the call once. The old API instance stays usable for in-flight callers and is closed after they drain.

• Transient errors (5xx, timeouts, connection resets) retry up to 3× with jittered exponential backoff. Rate limits (429) raise a dedicated error honoring Retry-After.

• Per-tool TTL cache (status 60 s, devices 24 h, energy_report 5 min, diagnostics not cached). Failures are never cached.

• All logs go to stderr through a SecretRedactor filter that scrubs credentials, tokens, serial numbers, and UUIDs.

Security

See SECURITY.md. Report security issues via GitHub Private Vulnerability Reporting, not as public issues.

Development

pip install -e '.[dev]' || pip install -r requirements-dev.txt
pytest
ruff check .
mypy

See CONTRIBUTING.md for fixture-capture and live-test workflows.

Credits

This project would not exist without:

• signalkraft/mypyllant — the reverse-engineered Python library that does all the actual API work. (PyPI)

• Model Context Protocol — the open protocol that makes this server interoperable across AI assistants.

• holger1411/polestar-mcp — pattern reference for the long-lived async client + TTL cache layout.

License

MIT.