# zont-mcp

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

[![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)
[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)

---

## Что это / 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: Установка

```bash
# Клонировать репозиторий
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

```bash
# 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` и заполните:

```bash
cp .env.example .env
```

```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:

```env
# 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`:

```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`:

```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](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 документация](https://zont-online.ru/api/docs/)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [Сайт ZONT](https://zont-online.ru)

---

## Лицензия / License

MIT — см. [LICENSE](LICENSE)