UniFi MCP服务器
用于UniFi网络管理的模型上下文协议(MCP)服务器,为全面的网络控制、监控和自动化提供了24个强大的工具。
特性
此MCP服务器通过Claude和其他MCP客户端提供完整的UniFi网络管理功能:
现场管理(3个工具)
- 现场健康监测 -获取站点整体健康状态和子系统得分
- 网站统计 -全面的网络使用和性能指标
- 系统信息 -控制器版本、主机名和配置详细信息
设备管理(6个工具)
- 列出设备 -查看所有UniFi设备(AP、交换机、网关)的状态
- 设备详细信息 -按MAC地址获取特定设备的详细信息
- 设备统计 -实时性能指标和使用统计数据
- 重启设备 -远程重启任何UniFi设备
- 采用设备 -将挂起的设备纳入您的网络
- 查找设备 -启用/禁用LED闪烁以识别物理设备
客户管理(5个工具)
- 列出客户 -查看所有连接的客户端(无线/有线/全部)
- 客户端详细信息 -获取特定客户的详细信息
- 阻止客户端 -通过MAC地址阻止客户端访问网络
- 解除阻止客户端 -恢复被阻止客户端的网络访问
- 重新连接客户端 -强制客户端重新连接(踢并允许重新连接)
无线网络管理(5个工具)
- 列出网络 -查看所有已配置的网络和VLAN
- 列出WLAN -查看所有无线网络(SSID)
- 启用WLAN -激活无线网络
- 禁用WLAN -停用无线网络
- 更新WLAN密码 -更改无线网络密码
交换机和端口管理(2个工具)
- 列出端口配置文件 -查看已配置的交换机端口配置文件
- 获取交换机端口 -查看特定交换机的端口配置和状态
安全和防火墙(1个工具)
- 列出防火墙规则 -查看所有已配置的防火墙规则
流量和分析(2个工具)
- 流量统计 -网络流量统计(每小时/每天/每月)
- DPI统计 -深度包检测和应用程序使用数据
警报和事件(2个工具)
- 列表警报 -查看最近的系统警报和报警
- 列出事件 -查看最近的网络事件和日志
访客通道(2个工具)
- 列出客人优惠券 -查看所有客人入场券
- 创建访客优惠券 -生成过期的新访客访问凭证
备份和维护(1个工具)
- 创建备份 -启动控制器配置备份
安装
先决条件
- Node.js 20.x或更高版本
- UniFi网络控制器(云网关、Dream Machine或自托管)
- UniFi管理员凭据
再进行```bash
npm install
### 构建服务器```bash
npm run build
编译后的JavaScript将输出到 dist/ 目录。
配置
使用环境变量配置服务器:
| 变量 | 描述 | 默认值 | 必填 |
|---|---|---|---|
UNIFI_URL |
UniFi控制器URL | https://192.168.1.1 |
是的 |
UNIFI_USERNAME |
管理员用户名 | admin |
是的 |
UNIFI_PASSWORD |
管理员密码 | - | 是 |
UNIFI_SITE |
站点名称/ID | default |
没有 |
配置示例
创建一个 .env 文件(未提交到git):```bash
UNIFI_URL=https://192.168.16.254
UNIFI_USERNAME=admin
UNIFI_PASSWORD=your_password_here
UNIFI_SITE=default
## 用法
### 使用克劳德桌面
添加到您的Claude Desktop配置文件中:
**窗户:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux:** `~/.config/Claude/claude_desktop_config.json````json
{
"mcpServers": {
"unifi": {
"type": "stdio",
"command": "node",
"args": ["C:/path/to/mcp-servers/unifi/dist/index.js"],
"env": {
"UNIFI_URL": "https://192.168.16.254",
"UNIFI_USERNAME": "admin",
"UNIFI_PASSWORD": "your_password_here",
"UNIFI_SITE": "default"
}
}
}
}
独立测试
直接运行服务器进行测试:```bash
npm start
或者在自动重新加载的开发模式下:```bash
npm run dev
工具参考
站点工具
unifi_get_site_health
获取总体站点健康状况和子系统状态得分。
参数: 无
示例响应:```json
[
{
"subsystem": "wan",
"status": "ok",
"num_user": 45,
"num_guest": 0
}
]
#### `unifi_get_traffic_stats`
获取网络流量统计数据。
**参数:**
- `timeframe` (可选): `hourly`, `daily`,或 `monthly`
#### `unifi_create_backup`
启动控制器配置备份。
**参数:** 无
### 设备工具
#### `unifi_list_devices`
列出所有UniFi设备的状态和基本信息。
**参数:**
- `type` (可选):按设备类型筛选(`uap`, `usw`, `ugw`, `udm`)
**示例响应:**```json
[
{
"name": "Office AP",
"mac": "aa:bb:cc:dd:ee:ff",
"type": "uap",
"model": "U6-LR",
"ip": "192.168.1.10",
"state": "connected",
"uptime": "15d 6h 30m",
"clients": 12
}
]
unifi_get_device
获取特定设备的详细信息。
参数:
mac(必填):设备MAC地址
unifi_restart_device
重新启动UniFi设备。
参数:
mac(必填):设备MAC地址
unifi_locate_device
启用设备上的LED闪烁以进行物理识别。
参数:
mac(必填):设备MAC地址
客户端工具
unifi_list_clients
列出所有连接的网络客户端。
参数:
type(可选):按连接类型筛选(all,wireless,wired)
示例响应:```json
[
{
"name": "iPhone",
"mac": "11:22:33:44:55:66",
"ip": "192.168.1.100",
"type": "wireless",
"signal": -45,
"uptime": "2d 4h 15m",
"tx_bytes": "1.2 GB",
"rx_bytes": "450 MB"
}
]
#### `unifi_get_client`
获取特定客户的详细信息。
**参数:**
- `mac` (必填):客户端MAC地址
#### `unifi_block_client`
阻止客户端访问网络。
**参数:**
- `mac` (必填):客户端MAC地址
#### `unifi_unblock_client`
解除对以前被阻止的客户端的阻止。
**参数:**
- `mac` (必填):客户端MAC地址
#### `unifi_reconnect_client`
强制客户端重新连接(踢并允许重新连接)。
**参数:**
- `mac` (必填):客户端MAC地址
### WLAN工具
#### `unifi_list_networks`
列出所有已配置的网络和VLAN。
**示例响应:**```json
[
{
"id": "507f1f77bcf86cd799439011",
"name": "Main LAN",
"purpose": "corporate",
"vlan": null,
"subnet": "192.168.1.1/24"
}
]
unifi_list_wlans
列出所有无线网络(SSID)。
示例响应:```json
[
{
"id": "507f1f77bcf86cd799439012",
"name": "Home WiFi",
"enabled": true,
"security": "wpapsk"
}
]
#### `unifi_enable_wlan`
启用无线网络。
**参数:**
- `wlan_id` (必填):WLAN ID来自 `list_wlans`
#### `unifi_disable_wlan`
禁用无线网络。
**参数:**
- `wlan_id` (必填):WLAN ID来自 `list_wlans`
#### `unifi_set_wlan_password`
更改无线网络的密码。
**参数:**
- `wlan_id` (必填):WLAN ID来自 `list_wlans`
- `password` (必填):新密码(8+个字符)
### 切换工具
#### `unifi_list_port_profiles`
列出所有已配置的交换机端口配置文件。
#### `unifi_get_switch_ports`
获取特定交换机的端口配置和状态。
**参数:**
- `mac` (必填):切换MAC地址
### 安全工具
#### `unifi_list_firewall_rules`
列出所有已配置的防火墙规则。
### 分析工具
#### `unifi_get_dpi_stats`
获取深度数据包检测统计数据和应用程序使用情况。
#### `unifi_list_alerts`
列出最近的系统警报。
**参数:**
- `limit` (可选):要返回的警报数量(默认值:50)
#### `unifi_list_events`
列出最近的网络事件。
**参数:**
- `limit` (可选):要返回的事件数(默认值:50)
### 访客访问工具
#### `unifi_list_vouchers`
列出所有客人入场券。
#### `unifi_create_voucher`
创建新的访客访问凭证。
**参数:**
- `count` (必填):要创建的凭证数量
- `expire_minutes` (必填):有效期(分钟)
- `note` (可选):凭证的说明/注释
**例子:**```json
{
"count": 5,
"expire_minutes": 1440,
"note": "Conference Day 1"
}
建筑
此MCP服务器由以下组件构建:
- TypeScript 用于类型安全和现代JavaScript功能
- @模型上下文协议/sdk 用于MCP协议实现
- 轴 用于UniFi API通信
- stdio传输 与MCP客户端无缝集成
局限性
此服务器提供 只读访问 对于大多数配置设置。虽然你可以:
- 启用/禁用WLAN
- 更改WLAN密码
- 阻止/取消阻止客户端
- 重新启动设备
- 创建备份
你 不能 直接:
- 创建新的网络或VLAN
- 修改防火墙规则
- 配置设备设置
- 更改DPI设置
- 修改交换机端口配置
对于高级配置更改,请使用UniFi网络控制器web界面。
安全注意事项
- 永不承诺
.env文件 具有版本控制凭据 - 使用 强密码 适用于UniFi管理员帐户
- 考虑 只读管理员帐户 如果你的控制器支持它们
- 启用 双因素身份验证 在您的UniFi帐户上
- 使用 超文本传输安全协议 在可能的情况下用于控制器连接
- 使用环境变量或秘密管理安全地存储凭据
故障排除
连接问题
如果您收到身份验证错误:
- 验证您的
UNIFI_URL正确且可访问 - 检查
UNIFI_USERNAME和UNIFI_PASSWORD是正确的 - 确保用户具有管理员权限
- 验证SSL证书设置(默认情况下,服务器禁用证书验证)
自签名证书
服务器自动接受自签名证书。如果需要强制证书验证,请修改 httpsAgent 配置在 src/index.ts.
调试模式
通过运行以下命令启用详细日志记录:bash
NODE_ENV=development npm start
贡献
欢迎投稿!拜托:
- 复刻仓库
- 创建要素分支
- 进行更改
- 如果适用,添加测试
- 提交拉取请求
许可证
MIT许可证-有关详细信息,请参阅许可证文件
相关项目
- 模型上下文协议 -MCP官方文件
- UniFi网络控制器 -UniFi硬件和软件
- 克劳德桌面版 -支持MCP的桌面客户端
支持
对于问题、疑问或贡献,请在GitHub上打开问题。
注: 这是一个非官方工具,不隶属于或认可Ubiquiti股份有限公司。
