F
licenseB
qualityD
maintenanceMCP server for UniFi Network Controller that provides full API coverage for managing APs, clients, WLANs, firewall rules, VLANs, port forwards, and more.
51
-
mcp-unifi
by pete-builds
mcp-unifi
자체 호스팅 UniFi 게이트웨이 관리를 위한 MCP 서버입니다. 장치, 네트워크/VLAN, WiFi SSID(전체 CRUD), 방화벽 규칙(전체 CRUD), 스위치 포트 프로필, 연결된 클라이언트를 다루는 15개의 도구와, 단일 호출로 격리된 IoT 서브넷(VLAN, SSID 및 방화벽 차단)을 프로비저닝하고 부분 실패 시 자동 롤백을 수행하는 create_iot_network 도구를 제공합니다.
FastMCP와 Streamable HTTP 전송을 기반으로 구축되었습니다. 로컬 API 키를 통해 UCG-Fiber, UDM Pro 또는 기타 UniFi OS 게이트웨이와 통신합니다. 사이트 관리자/클라우드 계정이 필요하지 않습니다.
모든 도구는 JSON을 반환합니다. 오류는 구조화된 {"error": "...", "stub_mode": bool} 객체로 반환되므로 게이트웨이 문제로 인해 MCP 루프가 중단되지 않습니다.
이유
오늘날 대부분의 UniFi 자동화는 컨트롤러 UI를 클릭하거나, 깨지기 쉬운 일회성 스크립트를 작성하거나, 무거운 커뮤니티 SDK를 가져오는 것을 의미합니다. mcp-unifi는 MCP 인식 클라이언트(Claude Code, Claude Desktop, 사용자 지정 에이전트)에 매주 수행하는 작업(IoT VLAN 생성, 방화벽 규칙 삭제, SSID 감사, 채택된 장치 나열)을 위한 작고 집중적이며 잘 정의된 인터페이스를 제공합니다.
복합 도구인 create_iot_network는 15단계의 UI 워크플로우를 단일 도구 호출로 줄여줍니다.
Related MCP server: UniFi MCP
빠른 시작
게시된 이미지를 가져와 실행합니다:
docker run --rm \
-p 3714:3714 \
-e STUB_MODE=true \
ghcr.io/pete-builds/mcp-unifi:0.2.0서버는 기본적으로 **스텁 모드(stub mode)**로 시작하며, 실제 UniFi 하드웨어 없이도 현실적인 모의 데이터를 반환합니다. Claude Code에 등록합니다:
claude mcp add unifi --transport http --scope user --url http://localhost:3714/mcp그런 다음 Claude Code에게 "내 UniFi 장치 나열해줘"라고 요청하면 두 개의 스텁 장치가 반환되는 것을 볼 수 있습니다.
실제 게이트웨이와 통신하려면 자격 증명을 전달하고 스텁 모드를 끕니다:
docker run --rm \
-p 3714:3714 \
-e STUB_MODE=false \
-e UNIFI_HOST=192.168.1.1 \
-e UNIFI_API_KEY=<your-local-api-key> \
ghcr.io/pete-builds/mcp-unifi:0.2.0게이트웨이의 **설정 → 제어 평면 → 통합(Settings → Control Plane → Integrations)**에서 API 키를 생성하십시오.
도구 참조
도구 | 서명 | 기능 |
|
| 상태, 가동 시간 및 라디오별 정보를 포함하여 채택된 게이트웨이, AP 및 스위치를 나열합니다. |
|
| 구성된 모든 네트워크/VLAN(서브넷, DHCP 범위, VLAN ID)을 나열합니다. |
|
| 새로운 VLAN 태그 네트워크를 생성합니다. |
|
| 기존 VLAN의 필드를 패치합니다. |
|
| VLAN을 삭제합니다. |
|
| 모든 WiFi SSID를 나열합니다. |
|
| 특정 VLAN에 바인딩된 새 SSID를 생성합니다. |
|
| 기존 SSID의 필드(이름, 암호, hide_ssid 등)를 패치합니다. |
|
| WiFi SSID를 삭제합니다. |
|
| 모든 방화벽 규칙을 나열합니다. |
|
| 방화벽 규칙을 생성합니다. |
|
| 방화벽 규칙을 삭제합니다. |
|
| 스위치 포트 프로필(PoE 모드, 네이티브 VLAN, 포워딩)을 나열합니다. |
|
| 현재 연결된 무선 및 유선 클라이언트(MAC, 호스트 이름, IP, 신호/만족도, AP 또는 스위치 포트, 가동 시간)를 나열합니다. |
|
| 일회성: VLAN + SSID + 격리 규칙, 실패 시 롤백 포함. |
모든 도구는 JSON 문자열을 반환합니다. 오류는 구조화된 {"error": "...", "stub_mode": bool} 객체로 반환되므로 Claude는 MCP 루프를 중단하지 않고 실패를 렌더링할 수 있습니다.
스텁 모드 vs 실제 모드
모드 | 사용 시기 | 동작 |
스텁 ( | 개발, 데모, 하드웨어 도착 전 Claude 흐름 연결 | 하나의 게이트웨이, 하나의 AP, 하나의 네트워크, 하나의 SSID, 하나의 방화벽 규칙, 두 개의 포트 프로필로 시드된 메모리 내 상태 머신. 생성/업데이트/삭제는 컨테이너 수명 동안 유지됩니다. 재시작 시 초기화됩니다. |
실제 ( | UCG-Fiber/UDM/기타 UniFi OS 게이트웨이를 사용한 프로덕션 | 로컬 API 키를 사용하여 게이트웨이와 HTTPS로 통신합니다. |
모드 전환은 코드 변경이 아닌 구성 변경입니다. 동일한 11개의 도구와 동일한 응답 형태를 가집니다.
구성
모든 구성은 환경 변수(및 존재하는 경우 .env 파일)에서 읽습니다. 구성은 시작 시 Pydantic에 의해 검증되며, 유효하지 않은 값은 유용한 메시지와 함께 즉시 실패합니다.
변수 | 유형 | 기본값 | 필수 | 참고 |
| bool |
| 아니오 |
|
| string |
| 실제 모드에서만 | 게이트웨이 IP 또는 호스트 이름(스키마 없음). |
| int |
| 아니오 | 게이트웨이용 HTTPS 포트. |
| string |
| 아니오 | 컨트롤러 사이트 식별자. |
| string |
| 실제 모드에서만 | 설정 → 제어 평면 → 통합에서 로컬 API 키. |
| bool |
| 아니오 | 게이트웨이에 실제 인증서를 설치한 경우 |
| string |
| 아니오 | 리터럴 |
| int (2-254) |
| 아니오 | IoT /24 내의 첫 번째 DHCP 임대 오프셋. |
| int (2-254) |
| 아니오 | IoT /24 내의 마지막 DHCP 임대 오프셋. |
| string |
| 아니오 | 바인딩 주소. |
| int |
| 아니오 | 수신 포트. |
| enum |
| 아니오 |
|
| enum |
| 아니오 | 프로덕션용 |
전체 예제는 .env.example에 있습니다.
MCP 클라이언트 설정
Claude Code
claude mcp add unifi --transport http --scope user --url http://<host>:3714/mcpClaude Desktop
claude_desktop_config.json에 다음을 추가합니다:
{
"mcpServers": {
"unifi": {
"transport": "streamable-http",
"url": "http://<host>:3714/mcp"
}
}
}일반 구성
http://<host>:3714/mcp에서 Streamable HTTP를 사용합니다. Streamable HTTP 전송(사양 2025-03-26+)을 지원하는 모든 MCP 클라이언트가 연결할 수 있습니다.
아키텍처
+---------------------+ Streamable HTTP +---------------------+
| MCP Client | --------------------------> | mcp-unifi |
| (Claude Code, etc) | <-------------------------- | (FastMCP server) |
+---------------------+ +----------+----------+
|
| HTTPS + X-API-Key
v
+----------+----------+
| UniFi OS Gateway |
| /proxy/network/... |
+---------------------+이 서버는 얇은 비동기 프록시입니다. MCP 도구 호출을 UniFi 컨트롤러 REST 호출로 변환하고, 응답을 구성하며, JSON을 반환합니다. 상태를 저장하지 않고, 클라우드로 호출하지 않으며, 들어오는 MCP 연결을 인증하지 않습니다(신뢰할 수 있는 LAN에서 실행하십시오).
보안 참고 사항
UNIFI_API_KEY는 컨테이너의 환경에만 존재합니다. 로그에 기록되지 않으며, MCP 응답으로 다시 에코되지 않으며, 이 서버에 의해 디스크에 기록되지 않습니다.WLAN 암호는 모든 도구 응답에서 나갈 때 스텁 모드에서도 삭제(
[REDACTED])됩니다.컨테이너는 UID 1000으로 실행되며, 셸, 홈 디렉토리, 읽기 전용 루트 파일 시스템(
/tmp는tmpfs) 및no-new-privileges가 적용됩니다.기본 이미지는 다이제스트로 고정됩니다. Python 종속성은 해시 잠금된
requirements.lock에서pip --require-hashes로 설치됩니다.게시된 이미지는
docker/build-push-action을 통한 빌드 출처 증명 및 SBOM이 포함된 다중 아키텍처(amd64/arm64) 이미지입니다.MCP 서버 자체는 인증되지 않습니다. 신뢰할 수 있는 LAN 경계, 인증이 있는 리버스 프록시 또는 Tailscale ACL 뒤에 배치하십시오.
취약점 보고서는 SECURITY.md를 참조하십시오.
개발
Python 3.13+ 및 Docker가 필요합니다.
# Clone + install dev deps
git clone https://github.com/pete-builds/mcp-unifi.git
cd mcp-unifi
python -m venv .venv && source .venv/bin/activate
pip install --require-hashes -r requirements-dev.lock
pip install -e . --no-deps
# Run the test suite (101 tests, ~95% coverage)
pytest
# Lint and format
ruff check src tests
ruff format src tests
# Type check (mypy strict)
mypy src/mcp_unifi
# Run the server locally in stub mode
python -m mcp_unifi.server
# Or build the image yourself instead of pulling from GHCR
cp docker-compose.example.yml docker-compose.yml
docker compose up --build테스트
======================= 101 passed in 1.5s =======================
Name Stmts Miss Branch BrPart Cover
-----------------------------------------------------------------
src/mcp_unifi/__init__.py 2 0 0 0 100%
src/mcp_unifi/clients/__init__ 3 0 0 0 100%
src/mcp_unifi/clients/stubs.py 70 1 6 0 99%
src/mcp_unifi/clients/unifi.py 82 0 12 0 100%
src/mcp_unifi/config.py 38 1 8 0 98%
src/mcp_unifi/healthcheck.py 18 1 0 0 94%
src/mcp_unifi/logging_setup.py 33 1 12 2 93%
src/mcp_unifi/models.py 6 0 0 0 100%
src/mcp_unifi/server.py 232 15 70 5 92%
-----------------------------------------------------------------
TOTAL 484 19 108 7 95%CI는 최소 80% 커버리지, ruff 린트, ruff 포맷, mypy strict, 그리고 HIGH 또는 CRITICAL 발견 시 실패하는 Trivy fs+image 스캔을 통과해야 합니다.
종속성 업데이트
requirements.lock 및 requirements-dev.lock 파일은 해시 고정되어 있습니다. requirements.in(또는 requirements-dev.in)을 편집한 다음 다시 생성합니다:
uv pip compile requirements.in --output-file requirements.lock --generate-hashes --python-version 3.13
uv pip compile requirements-dev.in --output-file requirements-dev.lock --generate-hashes --python-version 3.13Dependabot은 requirements.in 수준 업데이트 및 Docker 기본 이미지 다이제스트에 대해 매주 PR을 엽니다.
감사의 말
UniFi 컨트롤러 엔드포인트 경로는 sirkirby/unifi-mcp 프로젝트와 교차 참조되었습니다. 해당 저장소는 API 표면을 위한 연구 자료로 사용되었으며, 코드는 복사되지 않았습니다. 여기의 구현은 검증된 Forge 패턴을 따르는 독립적인 FastMCP + httpx 빌드입니다.
라이선스
MIT.
기여
이슈 및 풀 리퀘스트를 환영합니다. PR을 열기 전에:
ruff check,ruff format --check및mypy src/mcp_unifi가 깨끗한지 확인하십시오.테스트를 추가하거나 업데이트하고 커버리지를 80% 이상으로 유지하십시오.
로컬에서
pytest를 실행하고 제품군이 통과하는지 확인하십시오.[Unreleased]제목 아래에CHANGELOG.md를 업데이트하십시오.
This server cannot be deployed
Maintenance
ActivityActive
ResponsivenessSlow
Related MCP Connectors
Cloud-hosted MCP server for URnetwork VPN and Proxy
A MCP server built for developers enabling Git based project management with project and personal…
- ArcjetOAuthcom.arcjet
An MCP server for Arcjet - the runtime security platform that ships with your AI code.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Related MCP Servers
- AlicenseBqualityCmaintenanceAn MCP server that enables AI assistants to manage UniFi network infrastructure, including cloud management, local network devices, and Protect cameras, through natural language.62MIT
- AlicenseNot gradedqualityDmaintenanceA safety-first MCP server for managing UniFi networks, exposing 17 tools for telemetry, diagnostics, and guarded mutations with dry-run previews and confirm requirements.14MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for UniFi Network Controller enabling AI assistants to manage UniFi infrastructure via natural language. It supports firewall rules, IPv6, and uses lazy/eager tool modes to minimize context usage.6Mozilla Public 2.0