MCP 服务器

tuvio-vacuum

Enables control of Tuvio/Tuya robot vacuum cleaners via a local hub, supporting commands such as start, pause, home, set mode, suction, water level, and more.

README

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 - список возможностей.

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

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

pip install -r requirements.txt

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

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

Добавьте MCP-сервер в C:\Users\<USER>\.codex\config.toml по примеру из examples/codex-config.example.toml.
Скопируйте skills/tuvio-vacuum-control в C:\Users\<USER>\.codex\skills.
Перезапустите 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-хаб.