Metadata-Version: 2.4
Name: zont-mcp
Version: 1.3.2
Summary: MCP server for ZONT heating system control via AI / MCP-сервер для управления системой отопления ZONT через ИИ
Author: MAB2908
License: MIT License
        
        Copyright (c) 2026 zont-mcp contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/MAB2908/zont-mcp
Project-URL: Issues, https://github.com/MAB2908/zont-mcp/issues
Project-URL: Changelog, https://github.com/MAB2908/zont-mcp/blob/main/CHANGELOG.md
Keywords: zont,mcp,heating,smart-home,baxi,opentherm,claude
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Home Automation
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]<2,>=1.3.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-dotenv>=1.0.0
Dynamic: license-file

# zont-mcp

**[README на русском](README.ru.md)**

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.

```bash
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](docs/setup.md) for all snippets):

```json
{
  "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](docs/setup.md)
([по-русски](docs/setup.ru.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`](https://github.com/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.

| Aspect | defanator/zont_api | zont-mcp |
|--------|--------------------|----------|
| Purpose | Python library for developers | MCP server for AI assistants |
| Interface | `import zont_api` in code | Natural language via any MCP client |
| Boiler control | No | Yes — modes, temperatures, relays |
| Configuration writes | No | Yes — circuits, modes, sensors, weather curve |
| Radio sensor history | No | Yes |
| Diagnostics & analytics | No | Yes |
| Event journal | No | Yes |
| Prometheus exporter / CSV | Yes | No |
| Tests | pytest, tox, CI | unittest + GitHub Actions |

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

| Document | Purpose |
|----------|---------|
| [docs/setup.md](docs/setup.md) | Full installation guide: token, all MCP clients, troubleshooting ([по-русски](docs/setup.ru.md)) |
| [AGENTS.md](AGENTS.md) | Working rules for AI agents (English + [Russian](AGENTS.ru.md)) |
| [CAPABILITIES.md](CAPABILITIES.md) | Everything the server can and cannot do; z3k command dictionary |
| [examples/heating-check/](examples/heating-check/) | Example: full diagnostic session |
| [examples/vacation-mode/](examples/vacation-mode/) | Example: "leaving for a week" scenario |
| [examples/python-client/](examples/python-client/) | Example: use the API client directly from Python |
| [CHANGELOG.md](CHANGELOG.md) | Release history (English + Russian) |
| [SECURITY.md](SECURITY.md) | Credential handling, vulnerability reporting |

## Badges

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Tests](https://github.com/MAB2908/zont-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/MAB2908/zont-mcp/actions/workflows/tests.yml)
[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) — how to set up the project, run tests and
submit changes. Simple starter tasks are marked
[`good first issue`](https://github.com/MAB2908/zont-mcp/labels/good%20first%20issue).

## License

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