kwikset-mcp

Claude가 Kwikset Halo 계열 스마트 잠금장치(Halo, Halo Keypad, Halo Touch, Halo Select / Select Plus)의 상태를 확인하고 제어할 수 있게 해주는 MCP 서버입니다.

이 서버는 Kwikset 클라우드 API용 커뮤니티 유지 Python 클라이언트인 aiokwikset을 얇게 감싼 래퍼입니다. Home Assistant Kwikset 통합에서 사용하는 것과 같은 클라이언트입니다.

중요: Kwikset은 이 API를 공개하지 않으며 공식적으로 지원하지도 않습니다. aiokwikset은 이를 리버스 엔지니어링한 것이므로, Kwikset이 서버 측에서 무언가 바꾸면 깨질 수 있습니다. 이 서버에는 debug_api_surface 도구와 방어적 조회 기능이 포함되어 있어, 이런 깨짐이 조용한 완전 실패로 이어지지 않고 진단과 수정을 쉽게 할 수 있습니다.

이 서버는 실제 계정이나 잠금장치로 엔드투엔드 테스트되지 않았습니다. — aiokwikset의 공개 문서와 Home Assistant 통합 소스를 바탕으로 만들어졌으며, Kwikset 자격 증명이나 실제 잠금장치가 없는 상태에서 개발되었습니다. 아래 단계를 진행하고 첫 lock / unlock 호출을 스모크 테스트로 취급하세요. 어떤 것이든 api_mismatch 오류가 발생하면 그 오류(및 debug_api_surface 출력)를 Claude에 붙여넣어 이름이 일치하지 않는 메서드를 한두 개 수정하면 됩니다.

로그인이 별도 단계로 수행되는 이유

Kwikset 비밀번호가 LLM 대화를 절대 통과해서는 안 되기 때문입니다. 그래서 인증은 일반 터미널에서 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를 실행한 다음 활성화 명령을 다시 시도하세요.

그런 다음, 가상 환경이 활성화된 상태에서:

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

위의 --password 플래그보다는 환경 변수를 먼저 설정하는 방법 2가 권장됩니다 (명령줄 비밀번호는 ps aux/Task Manager를 통해 다른 프로세스에 보이고 셸 히스토리에 남기 때문입니다) — 문법은 셸마다 다릅니다:

# 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 / $KWIKSET_MFA_CODE로 전달). 어느 쪽이든 ~/.kwikset-mcp/tokens.json이 생성됩니다(소유자만 읽기/쓰기 가능) 그리고 이 단계 이후로는 비밀번호를 절대 다루지 않습니다 — MCP 서버는 저장된 토큰만 읽고 갱신할 뿐입니다.

3. Claude를 이 서버로 지정합니다.

   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

Claude Desktop인 경우, claude_desktop_config.json에 다음을 추가하세요. (Settings → Developer → Edit Config) 여기에서 이 디렉토리의 .venv 절대 경로로 대체합니다:

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

Windows에서는 command가 다음을 가리켜야 합니다. C:\\absolute\\path\\to\\kwikset-mcp\\.venv\\Scripts\\python.exe (JSON이므로 이중 백슬래시를 사용하세요).

그런 다음 Claude 클라이언트를 재시작하여 새 서버를 인식하도록 하세요.

4. 직접 시도해 보세요. "내 Kwikset 잠금장치 목록을 알려줘" 또는 "현관문은 잠겨 있어?" 같은 요청을 Claude에 해보세요 — list_locks / get_lock_status를 호출해야 합니다. 잠금 해제는 명시적인 요청이 필요합니다. unlock_door는 confirm=true로 호출해야만 동작하고, Claude는 해당 문을 잠금 해제하라고 명확히 요청한 경우에만 이 값을 쓰기 때문입니다.

노출되는 도구

재인증

토큰이 만료되어 자동으로 갱신할 수 없는 경우(예: Kwikset 비밀번호가 변경되었거나 MFA가 재설정됨), 도구 호출 시 지침이 포함된 auth_required 오류가 반환됩니다 — 그냥 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