Skip to main content
Glama
deenesjakoruzh
pete-builds

mcp-unifi

by pete-builds
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

mcp-unifi

CI Release License: MIT Python MCP Coverage

자체 호스팅 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 워크플로우를 단일 도구 호출로 줄여줍니다.

빠른 시작

게시된 이미지를 가져와 실행합니다:

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 키를 생성하십시오.

도구 참조

도구

서명

기능

list_devices

()

상태, 가동 시간 및 라디오별 정보를 포함하여 채택된 게이트웨이, AP 및 스위치를 나열합니다.

list_networks

()

구성된 모든 네트워크/VLAN(서브넷, DHCP 범위, VLAN ID)을 나열합니다.

create_vlan

(name, vlan_id, subnet, dhcp_start?, dhcp_stop?, purpose?)

새로운 VLAN 태그 네트워크를 생성합니다.

update_vlan

(network_id, updates)

기존 VLAN의 필드를 패치합니다.

delete_vlan

(network_id)

VLAN을 삭제합니다.

list_wlans

()

모든 WiFi SSID를 나열합니다.

create_wlan

(name, passphrase, network_id, security?, wpa_mode?, is_guest?, hide_ssid?, wlan_band?)

특정 VLAN에 바인딩된 새 SSID를 생성합니다.

update_wlan

(wlan_id, updates)

기존 SSID의 필드(이름, 암호, hide_ssid 등)를 패치합니다.

delete_wlan

(wlan_id)

WiFi SSID를 삭제합니다.

list_firewall_rules

()

모든 방화벽 규칙을 나열합니다.

create_firewall_rule

(name, ruleset, action, rule_index?, protocol?, src_address?, dst_address?, src_networkconf_id?, dst_networkconf_id?, enabled?)

방화벽 규칙을 생성합니다.

delete_firewall_rule

(rule_id)

방화벽 규칙을 삭제합니다.

list_port_profiles

()

스위치 포트 프로필(PoE 모드, 네이티브 VLAN, 포워딩)을 나열합니다.

list_clients

()

현재 연결된 무선 및 유선 클라이언트(MAC, 호스트 이름, IP, 신호/만족도, AP 또는 스위치 포트, 가동 시간)를 나열합니다.

create_iot_network

(name, vlan_id, passphrase, main_lan_subnet?, subnet?, isolate?, hide_ssid?)

일회성: VLAN + SSID + 격리 규칙, 실패 시 롤백 포함.

모든 도구는 JSON 문자열을 반환합니다. 오류는 구조화된 {"error": "...", "stub_mode": bool} 객체로 반환되므로 Claude는 MCP 루프를 중단하지 않고 실패를 렌더링할 수 있습니다.

스텁 모드 vs 실제 모드

모드

사용 시기

동작

스텁 (STUB_MODE=true, 기본값)

개발, 데모, 하드웨어 도착 전 Claude 흐름 연결

하나의 게이트웨이, 하나의 AP, 하나의 네트워크, 하나의 SSID, 하나의 방화벽 규칙, 두 개의 포트 프로필로 시드된 메모리 내 상태 머신. 생성/업데이트/삭제는 컨테이너 수명 동안 유지됩니다. 재시작 시 초기화됩니다.

실제 (STUB_MODE=false)

UCG-Fiber/UDM/기타 UniFi OS 게이트웨이를 사용한 프로덕션

로컬 API 키를 사용하여 게이트웨이와 HTTPS로 통신합니다. UNIFI_HOST 및 UNIFI_API_KEY가 필요합니다.

모드 전환은 코드 변경이 아닌 구성 변경입니다. 동일한 11개의 도구와 동일한 응답 형태를 가집니다.

구성

모든 구성은 환경 변수(및 존재하는 경우 .env 파일)에서 읽습니다. 구성은 시작 시 Pydantic에 의해 검증되며, 유효하지 않은 값은 유용한 메시지와 함께 즉시 실패합니다.

변수

유형

기본값

필수

참고

STUB_MODE

bool

true

아니오

false인 경우 실제 모드 자격 증명이 필요합니다.

UNIFI_HOST

string

""

실제 모드에서만

게이트웨이 IP 또는 호스트 이름(스키마 없음).

UNIFI_PORT

int

443

아니오

게이트웨이용 HTTPS 포트.

UNIFI_SITE

string

default

아니오

컨트롤러 사이트 식별자.

UNIFI_API_KEY

string

""

실제 모드에서만

설정 → 제어 평면 → 통합에서 로컬 API 키.

UNIFI_VERIFY_SSL

bool

false

아니오

게이트웨이에 실제 인증서를 설치한 경우 true로 설정합니다.

IOT_SUBNET_TEMPLATE

string

10.0.{vlan_id}.0/24

아니오

리터럴 {vlan_id} 플레이스홀더를 포함해야 합니다.

IOT_DHCP_START_OFFSET

int (2-254)

100

아니오

IoT /24 내의 첫 번째 DHCP 임대 오프셋.

IOT_DHCP_STOP_OFFSET

int (2-254)

200

아니오

IoT /24 내의 마지막 DHCP 임대 오프셋.

MCP_HOST

string

0.0.0.0

아니오

바인딩 주소.

MCP_PORT

int

3714

아니오

수신 포트.

LOG_LEVEL

enum

INFO

아니오

DEBUG, INFO, WARNING, ERROR, CRITICAL 중 하나.

LOG_FORMAT

enum

json

아니오

프로덕션용 json, 로컬 개발용 text.

전체 예제는 .env.example에 있습니다.

MCP 클라이언트 설정

Claude Code

claude mcp add unifi --transport http --scope user --url http://<host>:3714/mcp

Claude 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.13

Dependabot은 requirements.in 수준 업데이트 및 Docker 기본 이미지 다이제스트에 대해 매주 PR을 엽니다.

감사의 말

UniFi 컨트롤러 엔드포인트 경로는 sirkirby/unifi-mcp 프로젝트와 교차 참조되었습니다. 해당 저장소는 API 표면을 위한 연구 자료로 사용되었으며, 코드는 복사되지 않았습니다. 여기의 구현은 검증된 Forge 패턴을 따르는 독립적인 FastMCP + httpx 빌드입니다.

라이선스

MIT.

기여

이슈 및 풀 리퀘스트를 환영합니다. PR을 열기 전에:

  1. ruff check, ruff format --check 및 mypy src/mcp_unifi가 깨끗한지 확인하십시오.

  2. 테스트를 추가하거나 업데이트하고 커버리지를 80% 이상으로 유지하십시오.

  3. 로컬에서 pytest를 실행하고 제품군이 통과하는지 확인하십시오.

  4. [Unreleased] 제목 아래에 CHANGELOG.md를 업데이트하십시오.

This server cannot be installed

A
license - permissive license
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
0dRelease cycle
2Releases (12mo)

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/pete-builds/mcp-unifi'

If you have feedback or need assistance with the MCP directory API, please join our Discord server