kwikset-mcp

MCP-сервер, который позволяет Claude проверять состояние и управлять умными замками семейства Kwikset Halo (Halo, Halo Keypad, Halo Touch, Halo Select / Select Plus).

Это тонкая обёртка вокруг aiokwikset — поддерживаемого сообществом Python-клиента для облачного API Kwikset; того же, что используется в Home Assistant Kwikset integration.

Важно: Kwikset не публикует и официально не поддерживает этот API. aiokwikset получает его методом реверс-инжиниринга, поэтому он может сломаться, если Kwikset что-то изменит на серверной стороне. Этот сервер включает инструмент debug_api_surface и защитные проверки, чтобы такой сбой было легко диагностировать и исправить, а не получить тихий жёсткий отказ.

Это не проверено на реальной учётной записи и реальном замке — он написан по опубликованной документации aiokwikset и исходному коду интеграции Home Assistant, без доступа к учётным данным Kwikset и без физического замка. Выполите шаги ниже и относ1/замок как смоук-тест; если что-то вызывает ошибку api_mismatch, вставьте её (и вывод debug_api_surfase) обратно Claude, чтобы он исправил одно-два несовпадающих имени методов.

Почему вход в систему — отдельнный шаг

Ваш пароль Kwikset никогда не должен попадать в диалог с LLM. Поэтому утентификация виполняется один раз в обычном термиale через auth_setup.py, которая сохраняет локально только полученный токен сессии (и никогда — пароль). MCP-сервер читает и незаметно обновляет эти токены — он никогда не запрашивает ваш пароль ни у Claude, ни у вас в диалге с Claude.

Related MCP server: Seam MCP Server

Настройка

1. Установите зависи мости (Python 3.10+):

   cd kwikset-mcp
   python3 -m venv .venv

   Активируйте вертуальное окружение — команда зависит от вашей оболочки:

   # macOS / Linux (bash or zsh)
   source .venv/bin/activate

   # Windows PowerShell
   .venv\Scripts\Activate.ps1

   :: Windows Command Prompt (cmd.exe)
   .venv\Scripts\activate.bat

Вы поймёте, что всё получилось, когда в приглашении оболочки появится префикс (.venv). Если PowerShell отказывалась выплнить скрипт («в этой системе отлёчено выполнение сценариев»), сначалы выплните Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass, потом повтороне комаду актации.

The following must be with the venv active:

pip install -e .

2. Войдите один раз. Обётные данные можно задать тремя способами, они прочеряются в таком порядоке:

   # 1. Command-line flags (any OS/shell)
   python auth_setup.py --email you@example.com --password 'hunter2'
   
   # 3. Interactive prompt (any OS/shell; default if nothing else is given)
   python auth_setup.py

   Вариант 2 — сначала задать переменные окружения — предпочительнее, чем флаг --password выше (пароль, переданный в командной строке, виден остальным процессам через ps aux/Таск Meetingер и остаётся в истории оболочки), — но синтакссис за висит от оболочки:

   # macOS / Linux (bash or zsh)
   KWIKSET_EMAIL=you@example.com KWIKSET_PASSWORD='hunter2' python auth_setup.py

   # Windows PowerShell
   $env:KWIKSET_EMAIL = "you@example.com"
   $env:KWIKSET_PASSWORD = "hunter2"
   python auth_setup.py

   Если в учётной записи включена MFA, вас попросят ввеси код (или можно задать его с зарание через --mfa-code / $KWIKSESET_MFA_CODE). В лю лубом слу чае при этом созда ётся ~/.kwікset-mcp/tokеns.json (достоп на чтен/запisen only вла дельца) и в и тогда больше никогда не обра лай гируйте к вашему паролю — MCP-сервер випл нользует по л уч енный токен по вто рно and refresh его across silent.

3. Дакажите Claude на этот сервер.

   For Claude Code, в этом каталоге проекта:

   # macOS / Linux
   claude mcp add kwikset -- "$(pwd)/.venv/bin/python" -m kwikset_mcp.server

   # Windows PowerShell
   claude mcp add kwikset -- "$PWD\.venv\Scripts\python.exe" -m kwikset_mcp.server

   For Claude Desktop, add this to claude_desktop_config.json (Settings → Developer → Edit Config), replacing the absolute path to .venv of this directory:

   {
     "mcpServers": {
       "kwikset": {
         "command": "/absolute/path/to/kwikset-mcp/.venv/bin/python",
         "args": ["-m", "kwikset_mcp.server"]
       }
     }
   }

   На Windows in command use C:\\absolute\\path\\to\\kwikset-mcp\\.venv\\Scripts\\python.exe (use double slash, because JSON). Add double backslashes.

   Then restart the Claude client to load the new server.

4. Попробуйте. Спросите Claude, например: «перечисли мои замки Kwikset» или «заперта ли входная дверь?» — он должен вызвать list_locks / get_lock_status. Для разблокировки нужен явный запрос: unlock_door отказывается действовать, если его не вызвать с confirm=true, а Claude сделает это только тогда, когда вы чётко попросите разблокировать эту дверь.

Доступные инструменты

Повторная аутентификация

Если токены истекли и не могут быть незаметно обновлены (например, изменился пароль Kwikset или сброшен MFA), вызовы инструментов вернут ошиб쿠 auth_required with instruction — просто повторно запусстите python auth_setup.py.

Файлы

kwikset-mcp/
├── auth_setup.py           # run once, by hand, to log in
├── src/kwikset_mcp/
│   ├── auth.py              # local token file read/write
│   ├── client.py            # aiokwikset wrapper (locks, status, etc.)
│   └── server.py            # FastMCP server + tool definitions
├── pyproject.toml
└── requirements.txt