network-mcp

UniFi Dream Machine을 통한 홈 네트워크 관리를 위한 독립형 HTTP MCP 서버입니다.

현재 컨트롤러 구현은 로컬 UniFi Network UI/controller API를 사용합니다. 이 API는 일반 텍스트 장치 관리에 필요한 직접 클라이언트 차단 목록 동작을 지원하기 때문입니다. 나머지 애플리케이션은 작은 NetworkController 인터페이스에 의존하므로, 이는 나중에 공식 UniFi Network API로 교체하거나 보완할 수 있습니다.

설정

bun install
cp .env.example .env
bun run start

서비스는 기본적으로 127.0.0.1:4123에서 수신 대기합니다.

Docker

호스팅/홈 설정에서는 Docker Compose로 실행합니다:

cp .env.example .env
docker compose up -d --build

compose 파일은 서비스를 컨테이너 내부의 0.0.0.0에 바인딩하고, 호스트 루프백의 127.0.0.1:4123에서만 게시하며, LowDB 데이터를 ./data에 유지합니다.

코드 변경 후 재빌드/재시작:

docker compose up -d --build

로그 보기:

docker compose logs -f network-mcp

로그는 Winston을 사용하여 JSON 형식으로 stdout에 출력됩니다. LOG_LEVEL=debug로 설정하면 UniFi 요청 시간 및 MCP 요청 진단 정보가 포함됩니다.

엔드포인트

• GET /health

• POST /mcp

• GET /mcp

• DELETE /mcp

MCP_AUTH_TOKEN이 설정된 경우 /mcp에는 다음이 필요합니다:

Authorization: Bearer <token>

OpenCode 설정

/home/zac/.config/opencode/opencode.json에 원격 MCP 서버를 추가하세요:

{
  "mcp": {
    "home-network": {
      "type": "remote",
      "url": "http://127.0.0.1:4123/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:HOME_NETWORK_MCP_TOKEN}"
      }
    }
  }
}

MCP 구성을 변경한 후 호스팅된 OpenCode 서비스를 재시작하세요.

도구

• list_clients

• find_device

• add_tag

• remove_tag

• list_tags

• add_displayname

• block_device

• unblock_device

• block_by_tag

• unblock_by_tag

• show_blocked

• unblock_all

• recent_actions

MAC 주소는 장치의 표준 키입니다. 태그와 표시 이름은 DB_PATH 아래의 LowDB에 로컬로 저장됩니다.