UniFi MCP Server

mcp-name: io.github.mikeholownych/unifi-mcp

Claude와 같은 AI 어시스턴트에 UniFi Network 및 Protect 인프라 관리와 분석 기능에 대한 액세스를 제공하는 MCP(Model Context Protocol) 서버입니다.

크레딧: 이 프로젝트는 gbassaragh/Unifi-mcp의 포크로 시작하여 이후 완전히 독립적인 프로젝트로 발전했습니다. 훌륭한 출발점을 제공한 @gbassaragh에게 감사드립니다.

업스트림 대비 개선 사항

• 로컬 세션 인증 라우팅 수정 — UNIFI_MODE=local에서 요청은 이제 쿠키 + CSRF 세션 인증과 함께 기존 컨트롤러 API(/proxy/network)를 올바르게 사용합니다. 업스트림은 모드와 관계없이 항상 Integration API를 통해 라우팅했습니다.

• 모드 인식 기본 URL 해석 — api_base_url는 이제 무조건 Integration API 엔드포인트를 반환하는 대신 구성된 인증 모드를 존중합니다.

• 확장된 테스트 스위트 — 구성, 네트워크 클라이언트 동작, 서버 도구 등록, Protect 통합을 다루는 57개의 통과 테스트.

Related MCP server: UniFi MCP Server

기능

UniFi Network

• 장치 관리: UniFi 장치(AP, 스위치, 라우터) 나열, 재시작, 찾기, 업그레이드

• 클라이언트 관리: 연결된 클라이언트 모니터링, 차단/차단 해제, 트래픽 통계 보기

• 사이트 관리: 사이트 상태, 네트워크 구성, VLAN, 무선 설정 보기

• 통계 및 모니터링: 이벤트, 알람, 속도 테스트, DPI 통계

• AI 기반 인사이트: 네트워크 분석, 최적화 권장 사항, 문제 해결

UniFi Protect

• 카메라 관리: 카메라 나열, 상태 보기, 실시간 스냅샷 가져오기

• 시스템 모니터링: NVR 상태, 카메라 상태 요약

• 액세서리: 조명, 센서, 차임, 뷰어 관리

• 라이브뷰: 구성된 카메라 보기 레이아웃 접근

멀티-장치 지원

• 여러 UniFi 장치 구성(게이트웨이, NVR 등)

• 이름으로 특정 장치를 지정 — 모든 네트워크 및 Protect 도구는 선택적 device 매개변수를 허용합니다.

• 장치별 API 키: 각 구성된 장치는 자체 키로 인증합니다.

• 여러 장치에 걸친 Network 및 Protect 서비스 혼합

인증 모드

API 키(Integration API)를 사용하는 경우, 일부 컨트롤러 기능은 레거시 세션 인증(UNIFI_MODE=local)을 통해서만 사용할 수 있습니다: 네트워크 이벤트, 알람, DPI 통계, 속도 테스트, WLAN 구성, 방화벽 규칙, 포트 프로필, 라우팅 테이블. 이러한 기능을 위한 도구는 조용히 실패하는 대신 활성화 방법을 설명하는 명확한 오류를 반환합니다. 인사이트 도구는 정상적으로 저하되며 데이터 제한 사항을 보고합니다.

로컬 계정 참고: MFA로 보호되는 SSO/Ubiquiti 계정 관리자는 세션 로그인을 완료할 수 없습니다. UNIFI_MODE=local을 사용하려면 콘솔에서 로컬 관리자를 만드세요(Restrict to Local Access Only).

에이전트 스킬

번들로 제공되는 스킬(skills/)은 이 서버를 위한 검증된 워크플로를 에이전트에게 가르칩니다 — 컨트롤러 특유의 함정(Network 10에서 제거된 엔드포인트, zone-pair 규칙, WPA3 전환)을 포함합니다.

전체 문서: 사용 가이드, 예상 결과, 문제 해결, 새 기능 요청 방법은 SKILLS.md를 참조하세요.

빠른 참조

스킬 작동 방식

문제를 자연스럽게 설명하기만 하면 — 에이전트가 요청에 맞는 스킬을 매칭하고 해당 워크플로를 따릅니다:

• "인터넷이 끊겼어요" → unifi-internet-down이 WAN, 모뎀, 게이트웨이를 진단합니다.

• "내 WiFi에 누가 있지?" → unifi-whos-home이 장치를 나열하고 미확인 장치를 표시합니다.

• "내 네트워크를 감사해 줘" → unifi-network-audit이 전체 상태 보고서를 생성합니다.

• "새 TV를 설정해 줘" → unifi-setup-new-device가 WiFi 페어링을 안내합니다.

Write-gated 스킬(위에 표시됨)은 네트워크를 수정합니다 — 변경을 적용하기 전에 항상 승인을 요청합니다.

비기술적 사용자를 위한 스킬은 전문 용어를 피하고, 모든 기술 용어를 번역하며, 파괴적인 작업 전에 확인을 요구합니다.

설치(프로젝트별): .claude/skills/에 복사하세요:

git clone https://github.com/mikeholownych/unifi-mcp.git
mkdir -p .claude/skills && cp -r unifi-mcp/skills/* .claude/skills/

전체 사용 가이드, 예상 결과, 문제 해결, 새 기능 요청 방법은 SKILLS.md를 참조하세요.

스킬은 MCP 도구를 일반 이름(get_firewall_policies, …)으로 참조합니다. MCP 클라이언트가 자동으로 접두사를 추가합니다.

지원 하드웨어

• UniFi Dream Machine (UDM, UDM-Pro, UDM-SE)

• UniFi Cloud Gateway (UCG-Ultra, UCG-Fiber)

• UniFi Network Video Recorder (UNVR, UNVR-Pro)

• UniFi Network Application (자체 호스팅)

• Traditional Cloud Key (Gen1, Gen2, Gen2+)

설치

uv 사용(권장)

# Clone the repository
git clone https://github.com/mikeholownych/unifi-mcp.git
cd unifi-mcp

# Install dependencies
uv sync

pip 사용

pip install -e .

구성

프로젝트 루트에 .env 파일을 생성하세요(또는 환경 변수를 설정하세요). 모든 옵션은 .env.example을 참조하세요.

멀티-장치 구성(권장)

서로 다른 서비스로 여러 UniFi 장치를 구성하세요:

UNIFI_DEVICES='[
  {
    "name": "main-gateway",
    "url": "https://192.168.1.1",
    "api_key": "your-gateway-api-key",
    "services": ["network"],
    "site": "default"
  },
  {
    "name": "nvr",
    "url": "https://192.168.1.2",
    "api_key": "your-nvr-api-key",
    "services": ["network", "protect"],
    "site": "default"
  }
]'
UNIFI_VERIFY_SSL=false

장치 구성 필드:

참고: username 및 password 필드는 Protect 이벤트 도구(모션 이벤트, 스마트 감지)에만 필요합니다. 기본 카메라 작업은 API 키만으로 작동합니다.

API 키를 생성하려면:

1. UniFi 컨트롤러에 로그인하세요.

2. Settings → Control Plane → API로 이동하세요.

3. 적절한 권한으로 새 API 키를 생성하세요.

레거시 단일 장치 구성

하위 호환성을 위해 단일 장치 구성이 여전히 지원됩니다:

UNIFI_MODE=local_api_key
UNIFI_CONTROLLER_URL=https://192.168.1.1
UNIFI_CLOUD_API_KEY=your-api-key
UNIFI_SITE=default
UNIFI_VERIFY_SSL=false

로컬 세션 인증(기존)

사용자 이름/비밀번호 인증으로 전체 기능에 액세스하려면:

UNIFI_MODE=local
UNIFI_CONTROLLER_URL=https://192.168.1.1
UNIFI_USERNAME=local-admin
UNIFI_PASSWORD=your-password
UNIFI_SITE=default
UNIFI_IS_UDM=true
UNIFI_VERIFY_SSL=false

Cloud API (api.ui.com)

Ubiquiti Cloud API 액세스를 위해:

UNIFI_MODE=cloud
UNIFI_CLOUD_API_KEY=your-api-key

API 키는 unifi.ui.com → API 섹션에서 받으세요.

Claude Desktop 사용

Claude Desktop 구성에 추가하세요(Linux에서는 ~/.config/claude/claude_desktop_config.json, macOS에서는 ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "unifi": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/unifi-mcp", "python", "-m", "unifi_mcp.server"],
      "env": {
        "UNIFI_DEVICES": "[{\"name\":\"gateway\",\"url\":\"https://192.168.1.1\",\"api_key\":\"your-key\",\"services\":[\"network\"]},{\"name\":\"nvr\",\"url\":\"https://192.168.1.2\",\"api_key\":\"your-key\",\"services\":[\"network\",\"protect\"]}]",
        "UNIFI_VERIFY_SSL": "false"
      }
    }
  }
}

Claude Code / opencode 사용

# Add the MCP server
claude mcp add unifi -- uv run --directory /path/to/unifi-mcp python -m unifi_mcp.server

또는 opencode.json에서:

{
  "mcp": {
    "unifi": {
      "type": "local",
      "command": ["/path/to/unifi-mcp/.venv/bin/python", "-m", "unifi_mcp.server"],
      "enabled": true
    }
  }
}

사용 가능한 도구

멀티-장치 관리

• list_unifi_devices - 구성된 모든 UniFi 장치와 해당 서비스를 나열합니다.

장치 관리

• list_devices - 모든 UniFi 네트워크 장치를 나열합니다.

• get_device_details - 자세한 장치 정보를 가져옵니다.

• restart_device - 장치를 다시 시작합니다.

• locate_device - LED를 깜빡여 장치를 찾습니다.

• get_device_stats - 성능 통계를 가져옵니다.

• upgrade_device - 펌웨어를 업그레이드합니다.

• provision_device - 강제로 다시 프로비저닝합니다.

클라이언트 관리

• list_clients - 연결된 클라이언트를 나열합니다.

• list_all_clients - 알려진 모든 클라이언트를 나열합니다(오프라인 포함).

• get_client_details - 클라이언트 세부 정보를 가져옵니다.

• block_client / unblock_client - 클라이언트를 차단/차단 해제합니다.

• kick_client - 클라이언트 연결을 끊습니다.

• forget_client - 알려진 클라이언트에서 제거합니다.

• get_client_traffic - 트래픽 통계를 가져옵니다.

• reserve_client_ip - DHCP 예약을 통해 IP를 예약합니다.

사이트 관리

• list_sites - 모든 사이트를 나열합니다.

• get_site_health - 사이트 상태를 가져옵니다.

• get_site_settings - 사이트 설정을 가져옵니다.

• get_sysinfo - 시스템 정보를 가져옵니다.

• get_networks - 네트워크/VLAN 구성을 가져옵니다.

• get_wlans - 무선 네트워크 구성을 가져옵니다.

• get_port_profiles - 스위치 포트 프로필을 가져옵니다.

• get_firewall_rules - 레거시 방화벽 규칙을 가져옵니다.

• get_firewall_policies - 존 기반 방화벽 정책을 가져옵니다(UniFi Network 9+).

• get_routing_table - 라우팅 테이블을 가져옵니다.

• get_port_forwards - 포트 포워딩 규칙을 가져옵니다.

• create_port_forward / delete_port_forward - 포트 포워드를 관리합니다.

구성 관리(쓰기)

• create_wlan / update_wlan / delete_wlan - 무선 네트워크 관리

• create_firewall_policy / set_firewall_policy_enabled / delete_firewall_policy - 영역 기반 방화벽 정책 관리

• export_camera_clip - 카메라 녹화 클립을 MP4로 내보내기 (Protect)

• get_all_sites_health - 모든 사이트의 상태 개요

데이터를 삭제하거나 중단을 유발하는 도구는 MCP 주석을 통해 확인 게이트(confirm-gated)가 적용되거나 파괴적(destructive)으로 표시됩니다.

통계 및 모니터링

• get_network_health - 전반적인 네트워크 상태

• get_recent_events - 최근 이벤트

• get_alarms - 활성 알람

• archive_all_alarms - 모든 알람 보관

• run_speed_test - 속도 테스트 시작

• get_speed_test_status - 속도 테스트 결과 가져오기

• get_dpi_stats - DPI 통계

• get_traffic_summary - 트래픽 요약

AI 인사이트 도구

• analyze_network_issues - 종합적인 문제 분석

• get_optimization_recommendations - 구성 권장 사항

• get_client_experience_report - 클라이언트 품질 지표

• get_device_health_summary - 장치 상태 개요

• get_traffic_analysis - 트래픽 패턴 분석

• get_all_sites_health - 모든 사이트의 상태 개요

멀티 사이트 오케스트레이션

• get_global_inventory - 모든 컨트롤러의 통합 장치 인벤토리

• get_global_health - 모든 컨트롤러의 집계 상태 보고서

• get_global_client_summary - 모든 컨트롤러의 클라이언트 수, 상위 트래픽 클라이언트, 차단된 클라이언트

• troubleshoot_client - 심층 클라이언트 문제 해결

UniFi Protect

• list_cameras - 연결 상태와 함께 모든 카메라 나열

• get_camera_details - 상세 카메라 정보 가져오기

• get_camera_snapshot - 실시간 스냅샷 가져오기 (base64 JPEG)

• get_protect_system_info - NVR 시스템 정보 가져오기

• get_camera_health_summary - 문제를 포함한 카메라 상태 개요

• get_liveviews - 구성된 라이브뷰 레이아웃 가져오기

• get_protect_accessories - 조명, 센서, 차임, 뷰어 나열

UniFi Protect 이벤트 (사용자 이름/비밀번호 필요)

• get_motion_events - 최근 모션 이벤트 가져오기

• get_smart_detections - 스마트 감지 이벤트 가져오기 (사람, 차량, 동물, 택배)

• get_protect_event_summary - 유형별 모든 이벤트 요약

• get_recent_protect_activity - 최근 활동 빠른 개요

예시 대화

MCP 서버에 연결한 후 Claude에게 다음과 같이 요청할 수 있습니다:

네트워크 관리

• "내 모든 UniFi 장치 나열"

• "현재 네트워크 상태는?"

• "네트워크에서 문제를 분석해 줘"

• "어떤 최적화 권장 사항이 있나요?"

• "클라이언트 경험 지표를 보여줘"

• "MAC aa:bb:cc:dd:ee:ff 클라이언트를 문제 해결해 줘"

• "어떤 클라이언트가 가장 많은 대역폭을 사용 중인가요?"

• "펌웨어 업데이트가 필요한 장치가 있나요?"

• "최근 네트워크 이벤트를 보여줘"

• "속도 테스트를 실행해 줘"

UniFi Protect

• "내 모든 카메라 나열"

• "카메라 상태 요약을 보여줘"

• "현관 카메라에서 스냅샷을 가져와 줘"

• "내 NVR 상태는?"

• "연결이 끊긴 카메라가 있나요?"

• "Protect 액세서리를 보여줘"

Protect 이벤트 (자격 증명 필요)

• "최근 모션 이벤트를 보여줘"

• "지난 24시간 동안 어떤 스마트 감지가 있었나요?"

• "오늘 사람 감지가 있었나요?"

• "지난주 이벤트 요약을 제공해 줘"

• "현관 카메라의 최근 활동을 보여줘"

멀티 장치

• "구성된 UniFi 장치를 나열해 줘"

• "내 NVR의 카메라를 보여줘"

• "메인 게이트웨이의 네트워크 상태를 가져와 줘"

개발

테스트 실행

uv run pytest

코드 포맷팅

uv run ruff check .
uv run ruff format .

Docker

docker build -t unifi-mcp .
docker run -i --rm --env-file .env unifi-mcp

새 기능 요청

• 새 스킬: [Skill] 접두사를 사용하여 이슈를 여세요 — 문제, 워크플로, 예상 출력을 설명하세요

• 스킬 수정: [Skill: skill-name] 접두사를 사용하여 이슈를 여세요 — 무엇이 누락되었거나 고장났는지 설명하세요

• 새 도구: [Tool] 접두사를 사용하여 이슈를 여세요 — UniFi API 엔드포인트와 예상 형식을 포함하세요

자세한 기여 지침은 SKILLS.md를 참조하세요.

릴리스 기록은 CHANGELOG.md를, 기여는 CONTRIBUTING.md를 참조하세요.

보안 참고 사항

• 자격 증명은 환경 변수를 통해 전달됩니다 — .env를 커밋하지 마세요

• 자체 서명 인증서의 경우 SSL 검증이 기본적으로 비활성화됩니다

• 서버는 읽기 작업과 안전한 관리 명령만 노출합니다

• 파괴적 작업(사이트 삭제, 공장 초기화)은 노출되지 않습니다

• API 키는 안전하게 보관하고 주기적으로 교체해야 합니다

라이선스

MIT 라이선스

기여

기여를 환영합니다! 이슈를 열거나 풀 리퀘스트를 제출해 주세요.