HomeBoxMCP

집 안 인벤토리와 대화하세요. HomeBoxMCP는 작고 상태가 없는(stateless) MCP 서버로, Homebox 인벤토리를 모든 MCP 클라이언트에서 사용할 수 있게 해 줍니다. Claude든 프로토콜을 지원하는 무엇이든 좋아요. 드릴이 어디 있는지 물어보고, 영수증을 첨부한 새 구매를 등록하거나, 벽장 전체를 자연어로 다시 정리하세요.

"Where did I put the spare HDMI cables?"
"Add the new espresso machine to the kitchen — warranty expires 2028-04-01."
"Move everything on Shelf B to the garage overflow bin."

도구는 16개, 파일은 단 하나, 런타임 의존성은 0개 — Node 22와 node:http만 있으면 됩니다. Docker 컨테이너로 실행해 두고 잊으셔도 됩니다.

왜 이 서버인가

• 읽기 및 쓰기. 타사 읽기 전용 homebox-mcp와 혼동하지 마세요. 이것은 파일을 생성, 갱신, 이동, 삭제, 첨부합니다.

• Homebox v0.26.x를 대상으로 제작. 항목과 위치가 "entities"로 통합되고 라벨이 "tags"로 이름이 바뀐 entity API를 대상으로 합니다.

• 무상태 스트리밍 HTTP. 상태 저장소도, 데이터베이스도, 사이드카도 없습니다. 원할 때마다 다시 시작하세요.

• 명확하게 실패하고, 이상한 방식으로 저장되지 않습니다. --doctor는 서버가 요청을 받기 전에 Homebox 연결을 검증하고, 크기 초과 업로드는 불명문화한 422 대신 실제 크기와 함께 거부됩니다.

Related MCP server: AllOurThings MCP Server

빠른 시작

배포된 이미지를 받으세요:

docker run -d --name HomeBoxMCP -p 3334:3334 \
  -v /path/to/config:/config:rw \
  -v /path/to/inbox:/inbox:ro \
  ghcr.io/businessnone/homeboxmcp:latest

또는 소스에서 빌드하세요:

docker build -t homeboxmcp:latest .

MCP 클라이언트 위치를 http://your-host:3334/mcp로 지정하세요. 그 외의 경로는 강제로 쳐내지며, 다른 경로로 POST하면 올바른 엔드포인트를 알려주는 404를 반환합니다. 서버 설정기 상태는 curl http://your-host:3334/healthz로 확인할 수 있으며, 버전과 도구 수를 알려줍니다.

설정을 먼저 확인해 보려면? --doctor는 Homebox URL에 연결할 수 있는지 그리고 자격 증명이 실제로 동작하는지 확인하고, 안 되면 한 줄의 이상과 함께 0 아닌 종료 코드를 반환합니다:

docker run --rm -v /path/to/config:/config:ro \
  ghcr.io/businessnone/homeboxmcp:latest node /app/index.mjs --doctor

Unraid

Unraid 템플릿은 unraid/homeboxmcp.xml입니다. raw URL을 사용해 Docker → Add Container → Template에 추가하거나, 목록에 올라오면 Community Apps에서 설치하세요. 설정 경로와 inbox 경로를 직접 관리하는 share로 지정하고, 컨테이너가 LAN 밖에서 접근 가능하면 MCP 인증 토큰을 설정하세요.

설정

/config/config.json 작성:

{ "homeboxUrl": "http://homebox:7745", "apiKey": "..." }

또는 파일을 아예 생략하고 HOMEBOX_URL과 HOMEBOX_API_KEY를 사용하세요. 아니면 HOMEBOX_URL에 이메일/비밀번호를 사용해 HomeBoxMCP가 직접 로그인하게 할 수도 있습니다.

HomeBoxMCP를 자신의 머신 밖으로 노출한다면 MCP_AUTH_TOKEN을 설정하세요. 클라이언트는 이 토큰을 Authorization: Bearer <token>, X-MCP-Token, 또는 X-Homebox-MCP-Token으로 보낼 수 있습니다.

16가지 도구

읽기 — search_entities, entity_tree, get_entity, list_entity_types, list_entity_types, get_stats

쓰기 — create_location, create_item, update_entity, move_entity, delete_entity, create_tag

첨부 — list_inbox, upload_attachment, delete_attachment, link_external_attachment

첨부 파일과 인박스가 있는 이유

MCP 도구 호출은 JSON만 실리는 이진 데이터가 아닌 데이터입니다. 10MB 영수증을 base64로 인라인하면 파일을 하나 보낸에 모델 주변의 컨텍스트 약 13MB를 소모하게 됩니다. 그래서 파일은 읽기 전용 인박스 마운트를 통해 HomeBoxMCP에 대신 전달됩니다. 파일을 인박스 안에 넣고, 파일명으로 첨부하세요.

경로는 인박스 기준으로 해석되고, 인박스를 벗어나려는 경로 조합은 거부되어야 합니다. ../../etc/passwd와 절대 경로 모두 안전하게 처리됩니다. 유효한 첨부 유형은 attachment, photo, manual, warranty, receipt, thumbnail입니다.

창힐

이 저장소의 존재 이유는 HomeBoxMCP(당시에는 homebox-shim)가 디스크에 소스가 없는 채로 실행되는 것이 발견되었기 때문입니다. 유일한 index.mjs 복사본이 실행 중인 Docker 이미지 안에 있었고, Dockerfile은 어떤 곳에도 없었습니다. docker cp Homebox-Shim:/app/index.mjs로 복구했고, 이미지 자체 설정에서 Dockerfile을 다시 만들었습니다. 이제 이 저장소가 원본 소스 저장소이며, 이미지가 아니라 가 아닌 다시 만들어야 합니다.

복구하게 된 리뷰는 docs/SUPPORTABILITY.md를 참고하세요.

라이선스

MIT — LICENSE를 참고하세요.