kwikset-mcp

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

이 프로젝트는 이전 Python 버전을 Node.js로 다시 작성한 것입니다. Windows에서 Python 특유의 설정 문제(인터프리터 없음, virtualenv 활성화, PATH 별칭)를 피하고자 전환했습니다. Node에는 이전 버전이 의존했던 Python 라이브러리 aiokwikset과 정확히 대응하는 것이 없으므로, 이 버전은 Kwikset의 클라우드 API와 직접 통신합니다. 로그인은 AWS Cognito, 홈/기기/잠금/잠금 해제 처리에는 간단한 REST API를 사용합니다.

API 세부 정보의 출처: Kwikset은 공식 API를 제공하지 않습니다. 이 서버가 사용하는 Cognito 풀/클라이언트 ID, API 호스트, REST 경로는 Apache-2.0 라이선스로 공개된 homebridge-kwikset-halo(이 잠금장치용 커뮤니티 Homebridge 플러그인)의 소스에서 추출했습니다. 이 플러그인은 다시 이 값들을 처음 문서화한 aiokwikset에 공로를 인정합니다. 자세한 내용은 src/const.js와 src/cognito.js의 주석을 참조하세요. 이 방식은 Kwikset이 공식적으로 지원하는 것이 아니며, Kwikset 쪽에서 서버 설정을 바꾸면 동작이 중단될 수 있습니다.

테스트 상태: 이 서버의 모든 로직 조각 — Cognito 로그인 흐름(2단계 전화번호 인증 챌린지 포함), 토큰 갱신 및 영속화, REST 필드 매핑, unlock_door 확인 가드, 그리고 모든 MCP 엔드투엔드 테스트 — 는 AWS Cognito, Kwikset REST API, MCP SDK 대신 손으로 작성한 mock으로 검증했고, 모두 통과했습니다. 여기서 테스트하지 못한 것은 실제 Kwikset 서비스 호출입니다. 실제 계정과 물리적 잠금장치가 필요하기 때문입니다. 첫 list_locks 호출을 실제 스모크 테스트로 간주하세요. 호출 자체가 완전히 실패하면(단지 일부 필드가 null인 수준이 아니라면) 풀/호스트 상수가 오래된 것일 수 있습니다. 도구가 null을 반환하면 debug_raw_devices를 실행해 실제 필드 이름을 확인하고 src/kwikset-client.js와 비교해 보세요.

로그인이 별도 단계인 이유

Kwikset 비밀번호는 LLM 대화를 거쳐서는 안 됩니다. 따라서 인증은 일반 터미널에서 auth-setup.js를 통해 한 번만 수행되며, 결과로 얻은 세션 토큰만 로컬에 저장합니다(비밀번호는 저장하지 않습니다). MCP 서버는 연결할 때마다 그 토큰을 읽고 자동으로 갱신하며, Claude나 Claude를 통한 당신에게 비밀번호를 묻지 않습니다.

Related MCP server: Lutron Caseta MCP Server

설치

1. Node.js 설치 (18+): 아직 없다면 nodejs.org에서 LTS 설치 프로그램을 받으세요. 다음처럼 확인할 수 있습니다.

node --version

2. 의존성 설치 — 이 폴더 안에서 실행하세요.

npm install

3. 로그인을 한 번 하세요. 자격 증명은 세 가지 방법으로 지정할 수 있고, 다음 순서로 확인됩니다.

# 1. CLI flags (any OS/shell)
node auth-setup.js --email you@example.com --password "hunter2"

# 2. Environment variables (preferred over the flag above - a
#    command-line password is visible to other processes/users on the
#    machine and lands in shell history)

# macOS / Linux
KWIKSET_EMAIL=you@example.com KWIKSET_PASSWORD='hunter2' node auth-setup.js

# Windows PowerShell
$env:KWIKSET_EMAIL = "you@example.com"
$env:KWIKSET_PASSWORD = "hunter2"
node auth-setup.js

# 3. Interactive prompt (any OS/shell; default if nothing else is given)
node auth-setup.js

계정에 전화번호 인증이 필요하면 Kwikset이 문자로 보낸 코드를 입력하라는 메시지가 표시됩니다(또는 --mfa-code / $KWIKSET_MFA_CODE로 미리 전달할 수도 있습니다). 이 과정은 소유자만 읽고 쓸 수 있는 ~/.kwikset-mcp/tokens.json 파일을 생성합니다. 이후 비밀번호는 다시 사용되지 않습니다.

4. Claude에 서버를 연결하세요.

Claude Code에서는 이 프로젝트 디렉터리에서 다음을 실행합니다.

# macOS / Linux
claude mcp add kwikset -- node "$(pwd)/src/server.js"

# Windows PowerShell
claude mcp add kwikset -- node "$PWD\src\server.js"

Claude Desktop에서는 claude_desktop_config.json(Settings → Developer → Edit Config)에 다음 내용을 추가하세요. 이 폴더에 있는 src/server.js의 절대 경로로 바꿔서 넣어야 합니다.

{
  "mcpServers": {
    "kwikset": {
      "command": "node",
      "args": ["/absolute/path/to/kwikset-mcp/src/server.js"]
    }
  }
}

Windows에서 JSON 경로에는 이중 백슬래시를 사용합니다. 예: "C:\\Users\\you\\kwikset-mcp\\src\\server.js".

그런 다음 Claude 클라이언트를 다시 실행하면 새 서버를 인식합니다.

5. 사용해 보세요. Claude에게 "list my Kwikset locks" 또는 "is the front door locked?"처럼 물어보면 됩니다. 그러면 list_locks / get_lock_status를 호출할 것입니다. 잠금 해제는 명확한 요청이 필요합니다. unlock_door는 confirm=true로 호출해야만 실제 잠금 해제를 수행하며, Claude는 사용자가 해당 문을 잠금 해제하라고 명확히 요청한 경우에만 confirm=true를 전달합니다.

제공되는 도구

다시 인증

토큰이 만료되고 조용히 갱신할 수 없는 경우(예: Kwikset 비밀번호가 변경되었거나 2FA가 초기화된 경우) 도구 호출은 안내와 함께 auth_required 오류를 반환합니다. 그냥 node auth-setup.js를 다시 실행하세요.

파일

kwikset-mcp/
├── auth-setup.js           # run once, by hand, to log in
├── src/
│   ├── const.js             # Cognito pool/client IDs, API host (see caveats above)
│   ├── auth.js               # local token file read/write
│   ├── cognito.js            # AWS Cognito login/refresh (amazon-cognito-identity-js)
│   ├── kwikset-client.js     # REST calls: homes, devices, lock/unlock
│   └── server.js             # MCP server + tool definitions
├── package.json
└── .gitignore