zont-mcp

README на русском

A local MCP server that gives AI assistants natural-language control over ZONT heating systems (BAXI Connect+ and compatible controllers) — reading state, switching modes, boiler telemetry, diagnostics and configuration writes.

Demo

A conversation once the server is connected to any MCP client (Claude, Cursor, VS Code, …):

You:      Any boiler errors right now? If yes — what should I do?
Assistant: (calls get_boiler_errors)
          No active faults. Fault flags: none.
          Telemetry: flow temp 54.2 °C, setpoint 55 °C, modulation 34%, status: ch, flame.

You:      We're cold. Run a diagnosis.
Assistant: (calls diagnose_heating)
          Status: warning. The "Boiler circuit" has no active mode — it was
          lost after a controller reboot. Fix: enable the mode.
          (calls set_heating_mode, then get_device_state to verify)
          Done — mode "Comfort" is active, target 21.5 °C.

How it works:

┌─────────────┐   MCP (stdio)   ┌──────────┐   HTTPS    ┌─────────────────┐
│ AI assistant │ ◄──────────────► │ zont-mcp │ ─────────► │  ZONT cloud API │
└─────────────┘                  └──────────┘            └────────┬────────┘
                                                                     │
                                                            ┌────────▼────────┐
                                                            │  ZONT controller │
                                                            │  + boiler (bus)  │
                                                            └─────────────────┘

The server runs locally, opens no network ports and talks to exactly two official ZONT endpoints over HTTPS (my.zont.online/api and lk.zont-online.ru/api).

Quick start

Requirements: Python 3.11+, a ZONT account (zont-online.ru) with a registered device, any MCP-compatible client.

pip install zont-mcp        # from PyPI (Python Package Index)
# — or from source —
git clone https://github.com/MAB2908/zont-mcp.git && cd zont-mcp
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .

Get your API token: set ZONT_LOGIN + ZONT_PASSWORD, run zont-mcp once — the token is printed to stderr; then keep only the token.

Add to your MCP client (Claude Desktop claude_desktop_config.json shown; Cursor, VS Code and others use the same fields — see docs/setup.md for all snippets):

{
  "mcpServers": {
    "zont": {
      "command": "zont-mcp",
      "env": {
        "ZONT_CLIENT_EMAIL": "your@email.com",
        "ZONT_TOKEN": "your_token"
      }
    }
  }
}

Ask your assistant:

Show the list of my ZONT devices.

Credentials live only in environment variables / a local .env file — never in code. Full installation and configuration guide: docs/setup.md (по-русски).

Features

• 38 tools in 7 groups: device state, heating control, I/O and guard zones, history, analytics, configuration, commands & archives
• Boiler OpenTherm telemetry — flow temperature, setpoint, burner modulation, status flags
• Diagnostics with recommendations — known failure signatures: lost bus connection, mode reset after reboot, low pressure, dead radio sensors
• Configuration writes at web-cabinet level — circuits, modes, sensors, weather-compensation curve; every write is backed up and verified by re-reading
• Works with any MCP client — Claude Desktop, Claude Code, Cursor, VS Code, ZCode
• Safety by design — dangerous firmware commands (restart, deletion, SMS/calls) deliberately excluded; device passwords masked in responses

Comparison

The closest analogue is defanator/zont_api — a Python library for the ZONT API. zont-mcp used it as a knowledge source for the z3k_boiler_adapter data format.

Choose zont-mcp when you want to talk to your heating system; choose zont_api when you build your own Python software against the API.

Documentation & more examples

Badges

Contributing

See CONTRIBUTING.md — how to set up the project, run tests and submit changes. Simple starter tasks are marked good first issue.

License

MIT — see LICENSE. This is an independent project, not affiliated with ZONT or Micro Line; it uses only the official public ZONT API.