unifi-mcp

Example Corp / examplecorp UniFi 플릿을 공식 UniFi Site Manager API(api.ui.com)를 통해 Claude 사용자 지정 커넥터로 노출하는 읽기 전용 원격 MCP 서버입니다.

odoo-ticket-mcp 및 TRMM MCP 서버의 형제 프로젝트 — 동일한 아키텍처:

Claude (claude.ai / Claude Code)
   │  OAuth 2.0 bearer token (Microsoft Entra ID)
   ▼
nginx  — TLS, Anthropic egress-IP allowlist (160.79.104.0/21), 403 otherwise
   │  http://127.0.0.1:8097
   ▼
unifi-mcp container (Portainer stack, FastMCP 3.x, Streamable HTTP at /mcp)
   │  X-API-KEY (Site Manager API key, read-only usage)
   ▼
api.ui.com  — Site Manager API + connector proxy into each console's Network API

• 클라이언트 → 서버 인증: Microsoft Entra ID, resource-server 모드. 서버는 audience(대상)에 바인딩된 bearer 토큰을 검증하며, 절대 발급하지 않습니다. 액세스는 앱 등록의 Entra 그룹 구성원 자격으로 제어됩니다.

• 서버 → UniFi 인증: 고정 Site Manager API 키 1개(unifi.ui.com → API Keys에서 Site Manager + Network 애플리케이션 범위, All Sites로 생성). v1에서는 호출자 ID를 의도적으로 UniFi에 전달하지 않습니다.

• 네트워크 경로: 공용 DNS → nginx(TLS + Anthropic IP 허용 목록) → 컨테이너. 심층 방어: 허용 목록은 OAuth에 추가로 적용됩니다.

도구 (모두 읽기 전용)

Site Manager (플릿 전체):

커넥터 프록시 (콘솔별 드릴다운, VPN 불필요):

일반적인 흐름: unifi_list_hosts → 콘솔 선택 → unifi_network_sites → unifi_network_clients / unifi_network_device.

Related MCP server: UniFi MCP Server

로컬 개발

python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
copy .env.example .env    # fill in UNIFI_API_KEY; set MCP_AUTH_ENABLED=false
.venv\Scripts\python -m unifi_mcp
# → http://127.0.0.1:8000/mcp  (test with MCP Inspector)

MCP_AUTH_ENABLED=false는 엔드포인트를 개방합니다 — 로컬 테스트 전용이며 프로덕션에서는 절대 사용하지 마세요.

Entra ID 앱 등록 (1회)

주석이 포함된 버전은 TrmmMCPServer/ENTRA_SSO_PLAYBOOK.md를 참조하세요. 요약 — 다음 단계를 순서대로 수행하세요:

1. 앱 등록 → 새 등록 — 이름 UniFi MCP, 단일 테넌트, 리디렉션 URI는 아직 없음. 클라이언트 ID와 테넌트 ID를 복사하세요.

2. API 공개 → 애플리케이션 ID URI — 정확히 https://unifi-mcp.example.com/mcp로 설정(AADSTS9010010 방지).

3. API 공개 → 범위 추가 — access_as_user, 관리자와 사용자 동의 가능, 사용으로 설정.

4. 인증서 및 비밀 → 새 클라이언트 비밀 — claude-connector, 24개월. 값을 즉시 복사하세요.

5. 인증 → 플랫폼 추가 → 웹 — 리디렉션 URI https://claude.ai/api/mcp/auth_callback 및 https://claude.com/api/mcp/auth_callback.

6. 매니페스트 — requestedAccessTokenVersion을 2로 설정(발급자 불일치 401 방지).

7. 엔터프라이즈 애플리케이션 → UniFi MCP → 속성 — 할당 필요 = 예.

8. 엔터프라이즈 애플리케이션 → 사용자 및 그룹 — Unifi-MCP-Users 그룹을 추가하세요. 그룹 구성원 = 커넥터를 사용할 수 있는 사람입니다.

배포

PORTAINER_DEPLOY.md(Portainer Git 스택 + webhook 재배포) 및 deploy/nginx-unifi-mcp.conf(TLS + Anthropic IP 허용 목록)를 참조하세요.

claude.ai에서 커넥터 등록

설정 → 커넥터 → 사용자 지정 커넥터 추가:

인수 테스트

# 1. Discovery doc advertises the full resource scope (not api://…)
curl -s https://unifi-mcp.example.com/.well-known/oauth-protected-resource/mcp | jq .scopes_supported

# 2. Unauthenticated /mcp is challenged
curl -i https://unifi-mcp.example.com/mcp        # 401 + WWW-Authenticate: Bearer

# 3. Non-Anthropic source IP is blocked at nginx
curl -i https://unifi-mcp.example.com/mcp        # from anywhere else: 403

# 4. Health (host-local, bypasses nginx)
curl http://<docker-host>:8097/healthz                 # {"status":"ok","service":"unifi_mcp"}

# 5. In claude.ai: connect as a Unifi-MCP-Users member → tools appear;
#    non-member → AADSTS50105 at sign-in.