zont-mcp

MCP-сервер для управления системой отопления ZONT через ИИ MCP server for ZONT heating system control via AI

---

Что это / What this is

RU: Локальный MCP-сервер, который подключает ИИ-ассистентов (Claude и другие) к облачному сервису ZONT через официальный REST API. После подключения ИИ может получать данные о состоянии системы отопления и управлять ею на естественном языке.

Поддерживаемые устройства: BAXI Connect+, ZONT H-2000+, SMART NEW, H-1V, Climatic и все модели, совместимые с API ZONT.

EN: A local MCP server that connects AI assistants (Claude and others) to the ZONT cloud service via the official REST API. Once connected, the AI can read heating system state and control it using natural language.

Supported devices: BAXI Connect+, ZONT H-2000+, SMART NEW, H-1V, Climatic, and all models compatible with the ZONT API.

---

Возможности / Features

RU: 23 инструмента в 5 группах

Группа	Инструменты
Устройства и состояние	Список устройств, текущее состояние, контуры, ошибки котла, датчики
Управление отоплением	Режимы, целевые температуры, ГВС, настройки режимов
Входы/выходы и охрана	Реле, пользовательские команды, охранные зоны
История и события	Температуры, контуры, радиодатчики, журнал событий
Аналитика	Снимок системы, диагностика с рекомендациями, анализ периода

EN: 23 tools in 5 groups

Group	Tools
Devices & state	Device list, current state, circuits, boiler errors, sensors
Heating control	Modes, target temperatures, DHW, mode settings
I/O & security	Relays, custom commands, guard zones
History & events	Temperature history, circuit history, radio sensors, event log
Analytics	System snapshot, diagnostic with recommendations, period analysis

---

Установка / Installation

Требования / Requirements

• Python 3.11 или выше
• Аккаунт ZONT (zont-online.ru) с зарегистрированным устройством

RU: Установка

# Клонировать репозиторий
git clone https://github.com/your-username/zont-mcp.git
cd zont-mcp

# Создать виртуальное окружение
python -m venv .venv
source .venv/bin/activate          # Linux / macOS
# .venv\Scripts\activate           # Windows

# Установить зависимости
pip install -e .

EN: Installation

# Clone the repository
git clone https://github.com/your-username/zont-mcp.git
cd zont-mcp

# Create virtual environment
python -m venv .venv
source .venv/bin/activate          # Linux / macOS
# .venv\Scripts\activate           # Windows

# Install dependencies
pip install -e .

---

Настройка / Configuration

RU: Переменные окружения

Скопируйте .env.example в .env и заполните:

cp .env.example .env

# Адрес электронной почты аккаунта ZONT (обязательно)
ZONT_CLIENT_EMAIL=your@email.com

# Токен авторизации (предпочтительно)
ZONT_TOKEN=your_token_here

# Логин и пароль — только для первичного получения токена
# ZONT_LOGIN=your_login
# ZONT_PASSWORD=your_password

Как получить токен:

1. Укажите ZONT_LOGIN и ZONT_PASSWORD, оставьте ZONT_TOKEN пустым.
2. Запустите сервер — токен будет выведен в stderr.
3. Скопируйте токен в ZONT_TOKEN, логин и пароль можно убрать.

EN: Environment variables

Copy .env.example to .env and fill in:

# ZONT account email (required)
ZONT_CLIENT_EMAIL=your@email.com

# Auth token (preferred)
ZONT_TOKEN=your_token_here

# Login/password — only for initial token retrieval
# ZONT_LOGIN=your_login
# ZONT_PASSWORD=your_password

How to get a token:

1. Set ZONT_LOGIN and ZONT_PASSWORD, leave ZONT_TOKEN empty.
2. Start the server — the token will be printed to stderr.
3. Copy the token to ZONT_TOKEN and remove login/password.

---

Подключение к Claude / Connecting to Claude

RU: Claude Desktop

Добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "zont": {
      "command": "/path/to/zont-mcp/.venv/bin/python",
      "args": ["/path/to/zont-mcp/src/server.py"],
      "env": {
        "ZONT_CLIENT_EMAIL": "your@email.com",
        "ZONT_TOKEN": "your_token_here"
      }
    }
  }
}

Расположение файла конфигурации:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

EN: Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "zont": {
      "command": "/path/to/zont-mcp/.venv/bin/python",
      "args": ["/path/to/zont-mcp/src/server.py"],
      "env": {
        "ZONT_CLIENT_EMAIL": "your@email.com",
        "ZONT_TOKEN": "your_token_here"
      }
    }
  }
}

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

---

Примеры запросов / Example prompts

Проверь состояние котла и системы отопления.
Check the boiler and heating system status.

Установи температуру в доме 22 градуса.
Set the home temperature to 22 degrees.

Переключи всю систему в режим «Эконом» — уезжаю на неделю.
Switch the whole system to Economy mode — I'm leaving for a week.

Есть ли сейчас ошибки котла? Если есть — что делать?
Are there any boiler errors right now? If yes — what should I do?

Проанализируй работу системы за 7 дней и скажи, всё ли в порядке.
Analyse the heating system performance over the last 7 days.

Полный список примеров: examples/prompts.md

---

Структура проекта / Project structure

zont-mcp/
├── src/
│   ├── server.py           — точка входа MCP / MCP entry point
│   ├── zont_client.py      — клиент ZONT API / ZONT API client
│   └── tools/
│       ├── devices.py      — устройства и состояние / devices & state
│       ├── heating.py      — управление отоплением / heating control
│       ├── control.py      — входы/выходы и охрана / I/O & security
│       ├── history.py      — история и события / history & events
│       └── analytics.py    — аналитика / analytics
├── references/
│   ├── api-methods.md      — справочник API ZONT / ZONT API reference
│   └── tools-reference.md  — справочник инструментов / tools reference
├── examples/
│   └── prompts.md          — примеры запросов / example prompts
├── .env.example
├── .gitignore
├── CHANGELOG.md
├── LICENSE
├── pyproject.toml
└── README.md

---

Безопасность / Security

RU:

• Токен и пароль хранятся только в переменных окружения, не в коде.
• Файл .env добавлен в .gitignore — не попадёт в репозиторий.
• Токен можно отозвать в личном кабинете ZONT: my.zont.online/api/widget/v3/.
• Сервер работает локально через stdio — сетевых портов не открывает.

EN:

• Token and password are stored only in environment variables, not in code.
• .env is in .gitignore — will not be committed.
• Token can be revoked in ZONT account: my.zont.online/api/widget/v3/.
• Server runs locally via stdio — no network ports are opened.

---

Ссылки / Links

• ZONT API документация
• Model Context Protocol
• MCP Python SDK
• Сайт ZONT

---

Лицензия / License

MIT — см. LICENSE