一款基于 Python 的自托管 MCP 服务器，将 UniFi Network Controller 转化为 86+ 种 LLM 可调用工具。支持 Claude Desktop、mcp-cli 等客户端通过自然语言管理防火墙、VPN、WLAN、设备与客户端，具备上下文优化（Lazy/Eager 模式）和安全确认机制。
项目定位#
UniFi Network MCP Server 是一个 Model Context Protocol (MCP) 服务器，作为 UniFi Network Controller API 与 LLM 之间的桥梁，使 Claude Desktop、mcp-cli、LangChain 等支持 MCP 的客户端能够安全地查询、分析和修改网络配置。
核心能力#
网络管理#
- 完整操作目录：覆盖 Firewall、QoS、VPN、WLAN、Port Forwards、Traffic Routing 等配置
- 系统监控：支持查询 Stats、Events、Alarms、DPI 数据
- 设备与客户端：支持设备重启/升级、客户端列表、阻止/授权访客
MCP/LLM 集成#
- 上下文优化：
- Lazy 模式（默认）：仅注册 3 个元工具，消耗约 200 tokens（减少 96%）
- Eager 模式：注册全部 86+ 工具，消耗约 5,000 tokens
- Meta-Only 模式：仅注册元工具，需手动调用工具索引
- 代码执行：支持 JSON Schema 工具索引，支持批量并行执行
安全与运维#
- 安全确认机制：所有变更操作默认需
confirm=true，防止 LLM 幻觉导致的误操作 - 权限分级（v0.2.0 新增）：默认禁用高风险操作（网络修改/设备操作），默认启用只读与低风险策略操作
- 自动化友好：
UNIFI_AUTO_CONFIRM=true适配 n8n、Make、Zapier 等无交互场景
连接性#
- 多传输协议：stdio (FastMCP 主推)，可选 HTTP 端点 (Streamable HTTP/SSE)
- 控制器自动检测：自动识别 UniFi OS 代理路径与标准路径，检测耗时约 300ms
架构设计#
LLM Client (Claude/mcp-cli) <--(stdio/HTTP)--> UniFi Network MCP Server <--(HTTPS)--> UniFi Controller
- 核心框架：FastMCP（基于 MCP 协议）
- API 适配层：处理与 UniFi Network Controller 的 REST API 交互、认证与路径转换
- 工具注册系统：根据配置模式动态加载工具定义
部署方式#
Docker（推荐）#
docker pull ghcr.io/sirkirby/unifi-network-mcp:latest
docker run -i --rm \
-e UNIFI_HOST=192.168.1.1 \
-e UNIFI_USERNAME=admin \
-e UNIFI_PASSWORD=secret \
-e UNIFI_PORT=443 \
-e UNIFI_SITE=default \
-e UNIFI_VERIFY_SSL=false \
ghcr.io/sirkirby/unifi-network-mcp:latest
PyPI 安装#
pip install unifi-network-mcp
# 或使用 uv
uv pip install unifi-network-mcp
关键配置#
| 环境变量 | 说明 | 默认值 |
|---|---|---|
UNIFI_HOST | 控制器 IP/域名 | 必填 |
UNIFI_USERNAME | 本地管理员 | 必填 |
UNIFI_PASSWORD | 管理员密码 | 必填 |
UNIFI_SITE | 站点名称 | default |
UNIFI_AUTO_CONFIRM | 自动确认变更 | false |
UNIFI_TOOL_REGISTRATION_MODE | 工具加载模式 | lazy |
UNIFI_MCP_HTTP_ENABLED | 启用 HTTP 接口 | false |
适用场景#
- 智能家居/家庭实验室：通过 Claude Desktop 等客户端用自然语言管理家庭网络
- 运维自动化：集成至 n8n、Make、Zapier 实现基于事件的网络响应
- 网络分析：利用 LLM 分析 DPI 数据和系统事件生成健康报告