统一MCP服务器
项目介绍
UniFi MCP Server
一个模型上下文协议（MCP）服务器，暴露了UniFi网络控制器API，使AI代理和应用程序能够以标准化的方式与UniFi网络基础设施进行交互。
📋 版本通知
当前稳定版本: v0.1.4
注意：v0.2.0 发布过早，不应使用。请使用 v0.1.4，它包含了相同的代码并具有正确的版本号。真正的 v0.2.0 版本计划于2025年第四季度发布，并将包括基于区域的防火墙、流量流监控和其他主要功能。详情见 DEVELOPMENT_PLAN.md。
功能
核心能力
- 设备管理: 列出、监控、重启、定位和升级 UniFi 设备（接入点、交换机、网关）
- 网络配置: 创建、更新和删除网络、VLAN 和子网，带有 DHCP 配置
- 客户端管理: 查询、阻止、解除阻止和重新连接客户端
- 防火墙规则: 创建、更新和删除带有流量过滤的防火墙规则
- 基于区域的防火墙（ZBF）: 现代基于区域的安全性，带有区域管理（创建、读取、更新、删除区域和网络分配）。注意：区域策略矩阵和应用阻塞端点在 UniFi API v10.0.156 中不存在 - 需要通过 UniFi 控制台 UI 进行配置。详情见 ZBF_STATUS.md。
- WiFi/SSID 管理: 创建和管理带有 WPA2/WPA3 的无线网络、访客网络和 VLAN 隔离
- 端口转发: 配置端口转发规则以供外部访问
- 深度数据包检测统计: 应用程序和类别带宽使用的深度数据包检测分析
- 多站点支持: 无缝处理多个 UniFi 站点
- 实时监控: 访问设备、网络、客户端和 WiFi 统计信息
高级功能
- Redis 缓存: 可选的 Redis 基础缓存以提高性能（每种资源类型可配置 TTL）
- Webhook 支持: 实时事件处理，带有 HMAC 签名验证
- 自动缓存失效: 当配置更改时智能缓存失效
- 事件处理器: 内置设备、客户端和警报事件处理器
- 性能跟踪: 可选的 agnost.ai 集成，用于监控 MCP 工具性能和使用分析
安全性和安全性
- 确认所需: 所有变更操作都需要明确的
confirm=True标志 - 预演模式: 使用
dry_run=True预览更改后再应用 - 审计日志: 所有操作记录到
audit.log以符合合规性 - 输入验证: 全面的参数验证，带有详细的错误消息
- 密码屏蔽: 日志中敏感数据自动屏蔽
- 类型安全: 整个过程中的完整类型提示和 Pydantic 验证
- 安全扫描器: CodeQL、Trivy、Bandit、Safety 和 detect-secrets 集成
技术卓越
- 异步支持: 使用 async/await 构建，实现高性能和并发
- MCP 协议: 标准模型上下文协议，用于 AI 代理集成
- 全面测试: 213 个单元测试，覆盖率 37%（目标：80%）
- CI/CD 管道: 自动化测试、安全扫描和 Docker 构建
- 多架构: 适用于 amd64、arm64、arm/v7（32位 ARM）和 arm64/v8 的 Docker 镜像
快速开始
先决条件
- Python 3.10 或更高版本
- 在 unifi.ui.com 上的 UniFi 账户
- UniFi API 密钥（从设置 → 控制平面 → 集成获取）
- 访问 UniFi 云 API 或本地网关
安装
使用 uv（推荐）
# 如果尚未安装，请安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# 克隆仓库
git clone https://github.com/enuno/unifi-mcp-server.git
cd unifi-mcp-server
# 创建虚拟环境并安装依赖项
uv venv
source .venv/bin/activate # 在 Windows 上：.venv\Scripts\activate
uv pip install -e ".[dev]"
使用 pip
# 克隆仓库
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]"
使用 Docker Compose（推荐用于生产）
运行 UniFi MCP Server 并具有完整的监控功能的推荐方式：
# 1. 复制并配置环境变量
cp .env.docker.example .env
# 编辑 .env 文件，填写你的 UNIFI_API_KEY 和 AGNOST_ORG_ID
# 2. 启动所有服务（MCP Server + Redis + MCP Toolbox）
docker-compose up -d
# 3. 检查服务状态
docker-compose ps
# 4. 查看日志
docker-compose logs -f unifi-mcp
# 5. 访问 MCP Toolbox 仪表板
open http://localhost:8080
# 6. 停止所有服务
docker-compose down
包含的服务：
- UniFi MCP Server: 主 MCP 服务器，带有 77 个工具（69 个功能性，8 个已弃用）
- MCP Toolbox: 基于 Web 的分析仪表板（端口 8080）
- Redis: 高性能缓存层
详见 MCP_TOOLBOX.md 获取详细的 Toolbox 文档。
使用 Docker（独立）
对于独立的 Docker 使用（不与 MCP 客户端一起使用）：
# 拉取镜像
docker pull ghcr.io/enuno/unifi-mcp-server:latest
# 在后台运行容器（云 API）
# 注意：-i 标志保持标准输入打开以供 STDIO 传输
docker run -i -d \
--name unifi-mcp \
-e UNIFI_API_KEY=your-api-key \
-e UNIFI_API_TYPE=cloud \
ghcr.io/enuno/unifi-mcp-server:latest
# 或者使用本地网关代理运行
docker run -i -d \
--name unifi-mcp \
-e UNIFI_API_KEY=your-api-key \
-e UNIFI_API_TYPE=local \
-e UNIFI_HOST=192.168.1.1 \
ghcr.io/enuno/unifi-mcp-server:latest
# 检查容器状态
docker ps --filter name=unifi-mcp
# 查看日志
docker logs unifi-mcp
# 停止并移除
docker rm -f unifi-mcp
注意：对于 MCP 客户端集成（如 Claude Desktop 等），请参阅下方的 使用 部分，以获得正确的配置，不使用 -d 标志。
配置
获取您的 API 密钥
- 登录到 UniFi Site Manager
- 导航至 设置 → 控制平面 → 集成
- 点击 创建 API 密钥
- 立即保存密钥 - 它仅显示一次！
- 将其安全地存储在您的
.env文件中
配置文件
在项目根目录创建一个 .env 文件：
# 必需：您的 UniFi API 密钥
UNIFI_API_KEY=your-api-key-here
# API 类型：cloud 或 local
UNIFI_API_TYPE=cloud
# 对于云 API（默认）
UNIFI_HOST=api.ui.com
UNIFI_PORT=443
UNIFI_VERIFY_SSL=true
# 对于本地网关代理，使用：
# UNIFI_API_TYPE=local
# UNIFI_HOST=192.168.1.1
# UNIFI_VERIFY_SSL=false
# 可选设置
UNIFI_SITE=default
# Redis 缓存（可选 - 提高性能）
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
# REDIS_PASSWORD=your-password # 如果 Redis 需要身份验证
# Webhook 支持（可选 - 用于实时事件）
WEBHOOK_SECRET=your-webhook-secret-here
# 使用 agnost.ai 进行性能跟踪（可选 - 用于分析）
# 从 https://app.agnost.ai 获取您的组织 ID
# AGNOST_ENABLED=true
# AGNOST_ORG_ID=your-organization-id-here
# AGNOST_ENDPOINT=https://api.agnost.ai
# AGNOST_DISABLE_INPUT=false # 设置为 true 以禁用输入跟踪
# AGNOST_DISABLE_OUTPUT=false # 设置为 true 以禁用输出跟踪
详见 .env.example 获取所有可用选项。
运行服务器
# 开发模式，带有 MCP Inspector
uv run mcp dev src/main.py
# 生产模式
uv run python src/main.py
MCP Inspector 将在 http://localhost:5173 可用，用于交互式测试。
使用
与 Claude Desktop 结合使用
添加到您的 Claude Desktop 配置（macOS 上位于 ~/Library/Application Support/Claude/claude_desktop_config.json）：
选项 1：使用 uv（推荐）
{
"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"
}
}
}
}
选项 2：使用 Docker
{
"mcpServers": {
"unifi": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"UNIFI_API_KEY=your-api-key-here",
"-e",
"UNIFI_API_TYPE=cloud",
"ghcr.io/enuno/unifi-mcp-server:latest"
]
}
}
}
重要：在 MCP 客户端配置中不要使用 -d（分离模式）。MCP 客户端需要维持与容器的持久 stdin/stdout 连接。
程序化使用
from mcp import MCP
import asyncio
async def main():
mcp = MCP("unifi-mcp-server")
# 列出所有设备
devices = await mcp.call_tool("list_devices", {
"site_id": "default"
})
for device in devices:
print(f"{device['name']}: {device['status']}")
# 通过资源获取网络信息
networks = await mcp.read_resource("sites://default/networks")
print(f"网络数量: {len(networks)}")
# 创建带有 VLAN 隔离的访客 WiFi 网络
wifi = await mcp.call_tool("create_wlan", {
"site_id": "default",
"name": "访客 WiFi",
"security": "wpapsk",
"password": "GuestPass123!",
"is_guest": True,
"vlan_id": 100,
"confirm": True # 安全性所需
})
print(f"创建 WiFi: {wifi['name']}")
# 获取带宽使用最多的应用程序的 DPI 统计
top_apps = await mcp.call_tool("list_top_applications", {
"site_id": "default",
"limit": 5,
"time_range": "24h"
})
for app in top_apps:
gb = app['total_bytes'] / 1024**3
print(f"{app['application']}: {gb:.2f} GB")
# 创建基于区域的防火墙区域（UniFi Network 9.0+）
lan_zone = await mcp.call_tool("create_firewall_zone", {
"site_id": "default",
"name": "LAN",
"description": "可信本地网络",
"confirm": True
})
iot_zone = await mcp.call_tool("create_firewall_zone", {
"site_id": "default",
"name": "IoT",
"description": "物联网设备",
"confirm": True
})
# 设置区域到区域策略（LAN 可以访问 IoT，但 IoT 不能访问 LAN）
await mcp.call_tool("update_zbf_policy", {
"site_id": "default",
"source_zone_id": lan_zone["_id"],
"destination_zone_id": iot_zone["_id"],
"action": "accept",
"confirm": True
})
asyncio.run(main())
API 文档
详见 API.md 获取完整的 API 文档，包括：
- 可用的 MCP 工具
- 资源 URI 方案
- 请求/响应格式
- 错误处理
- 示例
开发
设置开发环境
# 安装开发依赖项
uv pip install -e ".[dev]"
# 安装 pre-commit 钩子
pre-commit install
pre-commit install --hook-type commit-msg
运行测试
# 运行所有测试
pytest tests/unit/
# 运行带有覆盖率报告的测试
pytest tests/unit/ --cov=src --cov-report=html --cov-report=term-missing
# 运行特定的测试文件
pytest tests/unit/test_zbf_tools.py -v
# 运行新 v0.2.0 特性的测试
pytest tests/unit/test_new_models.py tests/unit/test_zbf_tools.py tests/unit/test_traffic_flow_tools.py
# 仅运行单元测试（快速）
pytest -m unit
# 仅运行集成测试（需要 UniFi 控制器）
pytest -m integration
当前测试覆盖率：
- 总体：37.29%（213 个测试通过）
- ZBF 工具：84.13%（34 个测试）- 区域管理正常工作，策略矩阵/应用阻塞端点不存在
- 流量流工具：86.62%（16 个测试）
- 新 v0.2.0 模型：100%（36 个测试）
- 现有工具：15-95%（覆盖范围不同）
注意：ZBF 单元测试验证工具逻辑，但 8 个工具由于缺少 API 端点而无法工作（已在 v10.0.156 中验证）
详见 TESTING_PLAN.md 获取全面的测试路线图。
代码质量
# 格式化代码
black src/ tests/
isort src/ tests/
# 代码检查
ruff check src/ tests/ --fix
# 类型检查
mypy src/
# 运行所有 pre-commit 检查
pre-commit run --all-files
使用 MCP Inspector 测试
# 启动带有 inspector 的开发服务器
uv run mcp dev src/main.py
# 在浏览器中打开 http://localhost:5173
项目结构
unifi-mcp-server/
├── .github/
│ └── workflows/ # CI/CD 管道（CI、安全、发布）
├── .claude/
│ └── commands/ # 开发自定义斜杠命令
├── src/
│ ├── main.py # MCP 服务器入口点（注册了 77 个工具）
│ ├── cache.py # Redis 缓存实现
│ ├── config/ # 配置管理
│ ├── api/ # 带有速率限制的 UniFi API 客户端
│ ├── models/ # Pydantic 数据模型
│ │ └── zbf.py # 基于区域的防火墙模型
│ ├── tools/ # MCP 工具定义
│ │ ├── clients.py # 客户端查询工具
│ │ ├── devices.py # 设备查询工具
│ │ ├── networks.py # 网络查询工具
│ │ ├── sites.py # 站点查询工具
│ │ ├── firewall.py # 防火墙管理（第 4 阶段）
│ │ ├── firewall_zones.py # 基于区域的防火墙区域管理（v0.1.4）
│ │ ├── zbf_matrix.py # 基于区域的防火墙策略矩阵（v0.1.4）
│ │ ├── network_config.py # 网络配置（第 4 阶段）
│