ha-nexus-agent

Home Assistant용 MCP 서버 — AI 어시스턴트가 21개 도메인에 걸친 202개의 도구를 통해 스마트 홈을 완벽하게 제어할 수 있도록 합니다: 엔티티(일괄 제어 + 음성 노출 포함), 자동화 및 스크립트(전체 CRUD + 추적), 블루프린트, 대시보드, 도우미, 영역, 장치 레지스트리, 캘린더, 할 일 목록, 기록, 시스템 관리, YAML 구성 파일, Git 기반 버전 관리, 실시간 WebSocket 이벤트, 에너지 대시보드 기본 설정, 구역(지오펜싱), 라벨 및 카테고리, 퍼지 검색 및 탐색, Supervisor를 통한 애드온 관리, HACS 통합.

Claude Code CLI, Claude Desktop, VS Code, Cursor, Windsurf, OpenAI Codex CLI, Gemini CLI와 호환됩니다.

설치 — Home Assistant 애드온 (권장)

1. Home Assistant에서 설정 → 애드온 → 애드온 스토어로 이동합니다.

2. 점 3개 메뉴(⋮) → 저장소를 클릭합니다.

3. 다음을 추가합니다:

   https://github.com/Fistacho/ha-nexus-agent

4. Nexus Agent를 찾아 설치를 클릭합니다.

5. 시작을 클릭합니다.

6. 웹 UI 열기를 클릭합니다.

웹 UI에서 API 키를 확인하고 모든 MCP 클라이언트에 바로 붙여넣을 수 있는 구성을 생성할 수 있습니다. 수동 토큰 설정이 필요 없으며, 애드온이 Home Assistant에 자동으로 연결됩니다.

설치 — 독립형 (HA 외부)

git clone https://github.com/Fistacho/ha-nexus-agent
cd ha-nexus-agent
pip install -r requirements.txt
cp .env.example .env
# Edit .env: set HA_URL and HA_TOKEN
python server.py

**http://localhost:7123**에 접속하여 API 키와 MCP 클라이언트 구성을 확인하세요.

Home Assistant 토큰 얻기

1. HA에서 프로필 → 보안 → 장기 액세스 토큰으로 이동합니다.

2. 토큰 생성을 클릭하고 이름을 nexus로 지정합니다.

3. .env 파일에 HA_TOKEN으로 붙여넣습니다.

MCP 클라이언트 연결

Nexus를 시작한 후 **http://your-ha-ip:7123**에 접속하세요. 설정 페이지에서 각 클라이언트에 필요한 정확한 명령어나 구성 스니펫을 생성하므로 복사하여 붙여넣기만 하면 됩니다.

모든 SSE 기반 클라이언트는 다음 주소로 연결됩니다:

http://your-ha-ip:7123/mcp?token=YOUR_API_KEY

Claude Code CLI

claude mcp add nexus --transport sse "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY" --scope user

OpenAI Codex CLI

codex mcp add nexus --url "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY"

Gemini CLI

gemini mcp add nexus --url "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY"

VS Code

.vscode/mcp.json을 생성합니다:

{
  "servers": {
    "nexus": {
      "type": "sse",
      "url": "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY"
    }
  }
}

Cursor

~/.cursor/mcp.json에 붙여넣습니다:

{
  "mcpServers": {
    "nexus": {
      "url": "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY",
      "type": "sse"
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json에 붙여넣습니다:

{
  "mcpServers": {
    "nexus": {
      "url": "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY",
      "type": "sse"
    }
  }
}

Claude Desktop (독립형, 서브프로세스 모드)

%APPDATA%/Claude/claude_desktop_config.json(Windows) 또는 ~/Library/Application Support/Claude/claude_desktop_config.json(Mac)에 붙여넣습니다:

{
  "mcpServers": {
    "nexus": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "/path/to/ha-nexus-agent",
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "your_ha_token_here"
      }
    }
  }
}

팁: Nexus 웹 UI(http://your-ha-ip:7123)에서 실제 경로와 키가 포함된 정확한 구성을 복사하세요.

기능

• 21개 카테고리에 걸친 202개의 MCP 도구

• 실시간 WebSocket — 상태 변경, 이벤트 및 트리거를 실시간으로 구독

• Git 버전 관리 — 모든 구성 변경 사항이 자동 커밋되며 즉시 롤백 가능

• YAML 유효성 검사 — 구성 파일을 작성하기 전에 검사

• 설정 웹 UI — 모든 클라이언트에 대해 즉시 사용 가능한 MCP 구성을 자동 생성

• HA 애드온 네이티브 — 애드온 스토어에서 클릭 한 번으로 설치, 수동 토큰 설정 불필요

• API 키 인증 — MCP 엔드포인트 보호, URL 쿼리 매개변수를 통해 토큰 전달

도구 개요

Git 버전 관리

Nexus는 HA 구성 디렉토리의 Git 기록을 유지합니다. 위험한 변경을 수행하기 전에 git_safe_write_with_checkpoint를 사용하세요. 현재 상태를 먼저 커밋한 후 변경 사항을 적용합니다. 문제가 발생하면 즉시 롤백할 수 있습니다.

git_init_config()                                    # run once
git_safe_write_with_checkpoint("automations.yaml", new_content)
git_rollback_file("automations.yaml")                # undo single file
git_rollback_to_commit("abc1234")                    # full rollback
git_log(limit=10)                                    # see history

환경 변수