Tuvio Vacuum MCP + Skill

MCP-сервер и Codex skill для управления роботом-пылесосом Tuvio/Tuya через локальный хаб.

Проект не содержит ключей, токенов, QR-кодов и приватного состояния. MCP-сервер обращается к уже настроенному локальному хабу, а хаб хранит Tuya device_id и local_key у вас на компьютере.

Что внутри

• mcp_server/vacuum_mcp_server.py - MCP-сервер tuvio-vacuum;

• hub/minimal_hub.py - минимальный локальный HTTP-хаб для одного пылесоса;

• skills/tuvio-vacuum-control/SKILL.md - skill для Codex;

• examples/codex-config.example.toml - пример секции для ~/.codex/config.toml;

• docs/authorization.md - как получить авторизацию пылесоса до установки MCP;

• docs/minimal-hub.md - как запустить встроенный минимальный хаб;

• docs/install.md - установка MCP и skill;

• docs/capabilities.md - список возможностей.

Related MCP server: Eufy RoboVac MCP Server

Быстрый старт

1. Получите device_id и local_key пылесоса. Подробно: docs/authorization.md.

2. Установите зависимости:

pip install -r requirements.txt

3. Запустите встроенный минимальный хаб или свой совместимый хаб. Подробно: docs/minimal-hub.md.

4. Убедитесь, что хаб отвечает:

Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8790/api/devices

5. Добавьте MCP-сервер в C:\Users\<USER>\.codex\config.toml по примеру из examples/codex-config.example.toml.

6. Скопируйте skills/tuvio-vacuum-control в C:\Users\<USER>\.codex\skills.

7. Перезапустите Codex.

Что нужно новому владельцу Tuvio TR07MGBW

Этот репозиторий содержит MCP-сервер, Codex skill и минимальный локальный HTTP-хаб для одного пылесоса. Если у вас уже есть свой хаб, можно использовать его вместо встроенного.

Для рабочего запуска нужны:

• пылесос, добавленный в Smart Life / Tuya Smart / Tuya Home или совместимое OEM-приложение;

• device_id и актуальный local_key;

• встроенный хаб из docs/minimal-hub.md или свой локальный хаб с API из docs/hub-api.md;

• Python 3.10+ и доступ Codex к MCP-серверу.

Если после удаления или повторной привязки пылесоса команды перестали работать с ошибкой вида Check device key or version, получите новый local_key и обновите конфиг хаба. После перепривязки Tuya часто меняет локальный ключ.

Команды MCP

• vacuum_status

• vacuum_start

• vacuum_pause

• vacuum_home

• vacuum_find

• vacuum_set_mode

• vacuum_set_suction

• vacuum_set_water

• vacuum_drive

• vacuum_set_voice

• vacuum_set_power

• vacuum_reset_consumable

• vacuum_command

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

Не коммитьте:

• Tuya local_key;

• Tuya Client Secret;

• пароль роутера;

• hub_state.json;

• QR-коды авторизации;

• cookies и временные ответы Tuya Cloud.

Для локальных секретов используйте приватный конфиг хаба, .env или менеджер секретов.

Ограничения

Этот MCP-сервер не реализует сам Tuya Cloud и не извлекает local_key. Встроенный минимальный хаб тоже не получает ключ автоматически: он использует значения, которые вы укажете локально в hub/.env.

Карта квартиры, комнаты, запретные зоны, свои голосовые фразы, громкость голоса, выбор языка и датчик остатка воды в баке не поддерживаются, если их не отдает ваш Tuya-хаб.