UniFi MCP Server

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管理员凭据

再进行

npm install

构建服务器

npm run build

编译后的JavaScript将输出到 dist/ 目录。

配置

使用环境变量配置服务器：

配置示例

创建一个 .env 文件（未提交到git）：

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

{
  "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"
      }
    }
  }
}

独立测试

直接运行服务器进行测试：

npm start

或者在自动重新加载的开发模式下：

npm run dev

工具参考

站点工具

unifi_get_site_health

获取总体站点健康状况和子系统状态得分。

参数： 无

示例响应：

[
  {
    "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)

示例响应：

[
  {
    "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)

示例响应：

[
  {
    "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。

示例响应：

[
  {
    "id": "507f1f77bcf86cd799439011",
    "name": "Main LAN",
    "purpose": "corporate",
    "vlan": null,
    "subnet": "192.168.1.1/24"
  }
]

unifi_list_wlans

列出所有无线网络（SSID）。

示例响应：

[
  {
    "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 （可选）：凭证的说明/注释

例子：

{
  "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帐户上
• 使用 超文本传输安全协议 在可能的情况下用于控制器连接
• 使用环境变量或秘密管理安全地存储凭据

故障排除

连接问题

如果您收到身份验证错误：

1. 验证您的 UNIFI_URL 正确且可访问
2. 检查 UNIFI_USERNAME 和 UNIFI_PASSWORD 是正确的
3. 确保用户具有管理员权限
4. 验证SSL证书设置（默认情况下，服务器禁用证书验证）

自签名证书

服务器自动接受自签名证书。如果需要强制证书验证，请修改 httpsAgent 配置在 src/index.ts.

调试模式

通过运行以下命令启用详细日志记录：

NODE_ENV=development npm start

贡献

欢迎投稿！拜托：

1. 复刻仓库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

相关项目

• 模型上下文协议 -MCP官方文件
• UniFi网络控制器 -UniFi硬件和软件
• 克劳德桌面版 -支持MCP的桌面客户端

支持

对于问题、疑问或贡献，请在GitHub上打开问题。

______________________________________________________________________

注： 这是一个非官方工具，不隶属于或认可Ubiquiti股份有限公司。