项目简介

UniFi MCP Server 是一个基于 Model Context Protocol (MCP) 实现的服务器应用，旨在以标准化的方式将 Ubiquiti UniFi 网络控制器（UniFi Network Controller）的 API 功能暴露给大型语言模型（LLM）客户端和 AI 智能体。它允许 AI 应用通过统一的 MCP 接口来查询、配置和管理 UniFi 网络设备、客户端、网络设置、WiFi SSID、防火墙规则和端口转发等。

主要功能点

设备管理: 轻松列出、监控、重启、定位和升级您的 UniFi 接入点 (AP)、交换机和网关等设备。
网络配置: 创建、更新和删除网络、VLAN 和子网，并配置 DHCP 设置。
客户端管理: 查询连接的客户端信息，执行阻止、解除阻止和强制重连操作。
防火墙规则: 创建、修改和删除防火墙规则，实现流量过滤和安全策略。
WiFi/SSID 管理: 全面管理您的无线网络，包括创建新的 SSID，配置 WPA2/WPA3 安全，设置访客网络和 VLAN 隔离。
端口转发: 灵活配置端口转发规则，实现外部访问内部服务。
深度包检测 (DPI) 统计: 获取网络流量的深度分析，了解应用和类别级别的带宽使用情况。
多站点支持: 无缝管理多个 UniFi 站点。
实时监控: 获取设备、网络、客户端和 WiFi 的实时统计数据。
增强的安全与可靠性: 所有修改操作都需要明确确认（'confirm=True'），支持预演模式（'dry_run=True'）预览变更，并记录详细的审计日志。

安装步骤

克隆仓库: 使用 Git 命令将项目仓库克隆到您的本地机器。

git clone https://github.com/enuno/unifi-mcp-server.git
cd unifi-mcp-server

创建并激活虚拟环境:

python -m venv .venv
source .venv/bin/activate  # Windows 用户使用 .venv\Scripts\activate

安装依赖:

pip install -e ".[dev]"

服务器配置（适用于 MCP 客户端）

MCP 客户端（如 Claude Desktop）需要配置 UniFi MCP Server 的启动命令和环境变量才能与之连接。以下是配置信息的示例，您需要根据实际情况替换 'your-api-key-here' 和 '/path/to/unifi-mcp-server'：

{
  "mcpServers": {
    "unifi": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/unifi-mcp-server",
        "run",
        "mcp",
        "run",
        "src/main.py"
      ],
      "env": {
        "UNIFI_API_KEY": "your-api-key-here",
        "UNIFI_API_TYPE": "cloud"
      }
    }
  }
}

配置说明:

'"unifi"': 这是您为该 MCP 服务器自定义的名称，在 MCP 客户端中将以此名称引用。
'"command"': 启动 MCP 服务器的执行命令。这里推荐使用 'uv' 包管理器。
'"args"': 传递给 '"command"' 的参数列表。
- '"--directory", "/path/to/unifi-mcp-server"': 指定 UniFi MCP Server 仓库的本地路径，确保 MCP 客户端能够找到并启动服务器。
- '"run", "mcp", "run", "src/main.py"': 指定 'uv' 如何运行 MCP 服务器的核心入口文件 'src/main.py'。
'"env"': 运行服务器所需的环境变量。
- '"UNIFI_API_KEY"': 您必须从 UniFi Site Manager 获取的 API 密钥，用于认证 UniFi 控制器。请务必妥善保管。
- '"UNIFI_API_TYPE"': 指定连接 UniFi 控制器的方式。可以是 '"cloud"'（通过 UniFi 云端 API）或 '"local"'（直接连接本地控制器）。
- 如果 '"UNIFI_API_TYPE"' 设置为 '"local"'，您还需要在 'env' 中额外配置 '"UNIFI_HOST"' (例如 '"192.168.1.1"') 和可选的 '"UNIFI_PORT"' (默认 '8443')。

基本使用方法

获取 UniFi API 密钥: 登录 UniFi Site Manager，导航至 Settings → Control Plane → Integrations，创建并保存 API 密钥。

创建 '.env' 文件: 在项目根目录创建 '.env' 文件，并配置您的 API 密钥和 UniFi 控制器类型（云端或本地）。

UNIFI_API_KEY=your-api-key-here
UNIFI_API_TYPE=cloud
# 或者对于本地控制器，示例如下：
# UNIFI_API_TYPE=local
# UNIFI_HOST=192.168.1.1
# UNIFI_LOCAL_PORT=8443

运行 MCP 服务器:
- 开发模式 (带 MCP Inspector):
```
uv run mcp dev src/main.py
```
  此时您可以在 'http://localhost:5173' 访问 MCP Inspector 进行交互式测试。
- 生产模式:
```
uv run python src/main.py
```
通过 AI 客户端交互: 一旦 UniFi MCP Server 运行，任何兼容 MCP 协议的 AI 客户端（如 Claude Desktop）都可以通过上述配置连接到此服务器，并开始调用其提供的工具（如 'list_devices'、'create_wlan'）和访问资源（如 'sites://default/devices'），从而实现对 UniFi 网络的智能化管理。

关键词

项目简介

主要功能点

安装步骤

服务器配置（适用于 MCP 客户端）

基本使用方法

信息