Skip to main content
Glama
deeneszh
mbgroen

UniFi MCP

by mbgroen
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

UniFi MCP

CI License: MIT

一个用于 UniFi Network 和 UniFi Protect 的 Model Context Protocol 服务器，让 AI 助手能够回答关于你网络的问题——如果你允许的话——并对其执行操作。

它直接通过你的本地网络与 UniFi OS 控制台（UDR、UDM/UDM-Pro/SE、UCG、Cloud Key）通信。无需云服务，无需 Ubiquiti 账户，除了你选择与助手共享的内容外，没有任何数据离开你的局域网。

适用于任何 MCP 客户端。它既可作为 Claude Desktop 的一键式 .mcpb 插件，也可作为 可通过 npx 运行的服务器，还可作为普通的 Node 项目发布。

你可以询问什么

现在哪些设备连接在我的 WiFi 上，它们连接在哪个接入点上？ 网络上是否有设备连接状态不佳？ 显示昨晚的门铃事件。 从前门摄像头拍摄一张快照。 哪些端口从互联网转发了？ 重启客厅的接入点。（需要启用操作权限）

Related MCP server: UniFi MCP Server

亮点

  • 网络：设备、客户端（实时和历史）、WiFi 网络、VLAN 和子网、防火墙规则、端口转发、站点健康状况和 WAN 状态、事件日志、警报、历史统计、访客券。

  • Protect：摄像头和门铃、以图像形式返回的实时快照、移动/响铃/智能检测事件、传感器、灯光、门铃、RTSPS 流 URL。

  • 三个权限层级——默认只读；操作和配置更改是可选开关。

  • 两种认证方式——官方 API 密钥和/或本地管理员账户，每种方式解锁 UniFi API 的不同部分。同时使用两者可获得最全面的覆盖。

  • 紧凑输出——每个列表工具默认进行摘要（detail: "full" 返回原始 UniFi 对象），使响应保持可读且成本低廉。

  • 逃生通道——unifi_raw_request 可访问任何没有专用工具支持的端点。

要求

  • 可从运行 MCP 服务器的机器访问的 UniFi OS 控制台。

  • Node.js 20.18.1 或更高版本（仅适用于 npx / 源码安装——.mcpb 插件使用 Claude Desktop 自带的运行时）。

  • 凭据，请参阅 认证。

安装

选项 A — Claude Desktop 插件（.mcpb）

  1. 从 最新版本 下载 unifi-mcp-<version>.mcpb。

  2. 打开 Claude Desktop → 设置 → 扩展，将文件拖入（或双击它）。

  3. 在设置面板中填写控制台地址和凭据，并决定是否允许操作。

所有内容都已打包，因此无需单独安装 Node。

下面的 npx 示例使用已发布的 npm 包。在首次 npm 发布之前，你可以直接将 npx 指向仓库：npx -y github:mbgroen/unifi-mcp。

选项 B — Claude Code

claude mcp add unifi \
  --env UNIFI_HOST=192.168.1.1 \
  --env UNIFI_USERNAME=mcp-readonly \
  --env UNIFI_PASSWORD='your-password' \
  --env UNIFI_API_KEY='your-api-key' \
  -- npx -y @mbgroen/unifi-mcp

选项 C — 任何其他 MCP 客户端

将此添加到客户端的 MCP 服务器配置中（Cursor、VS Code、Windsurf、Zed、自定义主机）：

{
  "mcpServers": {
    "unifi": {
      "command": "npx",
      "args": ["-y", "@mbgroen/unifi-mcp"],
      "env": {
        "UNIFI_HOST": "192.168.1.1",
        "UNIFI_API_KEY": "your-api-key",
        "UNIFI_USERNAME": "mcp-readonly",
        "UNIFI_PASSWORD": "your-password",
        "UNIFI_PERMISSION_MODE": "read-only"
      }
    }
  }
}

选项 D — 从源码安装

git clone https://github.com/mbgroen/unifi-mcp.git
cd unifi-mcp
npm install
npm run build
cp .env.example .env   # fill it in
node dist/index.js     # speaks MCP over stdio

认证

UniFi OS 暴露了两个 API 系列，它们不可互换。此服务器支持两者，并选择已配置的那个——同时设置两者可获得最全面的覆盖。

API 密钥

本地账户

位置

设置 → 控制平面 → 集成 → 创建 API 密钥

设置 → 管理员 → 添加管理员（仅限本地访问，无 2FA）

变量

UNIFI_API_KEY

UNIFI_USERNAME + UNIFI_PASSWORD

覆盖范围

官方支持的子集：站点、设备、客户端、访客券、Protect 摄像头/快照

UniFi Web 应用自身使用的所有内容：统计、事件、警报、防火墙、端口转发、WLAN/VLAN 配置、Protect 事件日志

稳定性

稳定，有文档

非官方；可能随 UniFi 更新而变化

对于只读设置，请创建一个具有 查看者 角色的专用本地管理员。操作和配置更改需要具有管理员权限的账户。

本地账户不支持双因素认证——会话登录无法提示输入验证码。请为此服务器创建一个不带 2FA 的单独本地账户。（你自己的账户保留其 2FA。）

权限层级

服务器拒绝暴露其不允许运行的工具——不允许的工具不仅在调用时被阻止，而且永远不会被列出。

模式

UNIFI_PERMISSION_MODE

插件开关

新增内容

只读（默认）

read-only

两者均关闭

仅读取。你网络上的任何内容都不会改变。

操作

safe

允许操作

阻止/解除阻止客户端、重新连接客户端、重启设备、闪烁其 LED、对 PoE 端口断电重启、切换 SSID、运行速度测试、管理访客券、重命名客户端、设置门铃消息。所有操作均可逆。

完全控制

full

允许配置更改

防火墙规则、端口转发、WiFi 和网络设置、固件升级、Protect 录制模式，以及通过 unifi_raw_request 的写入访问权限。

从只读开始。只有当你希望助手实际更改某些内容时才提高权限，并记住助手会根据其读取的内容采取行动——包括来自网络本身的设备名称和备注。

工具

只读

工具

功能说明

控制台

unifi_status

检查与 UniFi 控制台的连接：哪些凭据有效、哪些应用可访问，以及此服务器当前被允许执行哪些操作。出现故障时请先使用此工具。

unifi_raw_request

针对没有专用工具的端点的逃生通道。GET 在所有权限模式下均可用；其他方法需要完全控制权限。路径相对于所选的 API 表面。

UniFi Network

unifi_list_sites

列出此控制台上的 UniFi Network 站点，并带有可传递给其他工具的站点名称。

unifi_list_devices

列出已纳管的 UniFi 设备（网关/路由器、接入点、交换机），包含型号、状态、固件、运行时间、客户端数量和负载。

unifi_get_device

通过 MAC 地址获取单个 UniFi 设备的完整详情，包括无线电、端口、温度和上行链路。

unifi_list_clients

列出网络上的客户端，包含 IP、信号、吞吐量以及它们使用的接入点或交换机端口。

unifi_list_known_clients

列出控制器曾见过的所有客户端，包括离线的客户端，以及它们的固定 IP、备注和阻止状态。

unifi_list_wlans

列出已配置的 SSID，包含安全设置、频段和启用状态。

unifi_list_networks

列出 LAN、VLAN 和 WAN 配置，包括子网和 DHCP 范围。

unifi_list_port_forwards

列出网关上的端口转发规则。

unifi_list_firewall_rules

列出网关上配置的防火墙规则（以及可选的防火墙组）。

unifi_site_health

每个子系统（WAN、LAN、WLAN、VPN）的整体健康状况：状态、运行时间、延迟、吞吐量以及最近一次测速结果。

unifi_list_events

最近的 Network 事件：客户端连接/断开、漫游、设备重启、配置更改。

unifi_list_alarms

Network 应用产生的未处理（或已存档）警报。

unifi_get_stats

站点、接入点、网关或单个客户端的时间序列统计（吞吐量、客户端、延迟）。

unifi_list_vouchers

列出访客热点券，包含时长、配额和使用情况。

UniFi Protect

unifi_protect_info

在此控制台上运行的 UniFi Protect NVR 的版本、存储和录制状态。

unifi_protect_list_cameras

列出摄像机和门铃，包含连接状态、录制模式、电池电量以及最近一次移动侦测/响铃。

unifi_protect_get_camera

单个摄像机或门铃的完整详情，包括其功能标志和设置。

unifi_protect_snapshot

从摄像机或门铃获取当前静态图像，并以图片形式返回，以便直接查看。

unifi_protect_list_events

最近的 Protect 事件：移动侦测、智能检测（人员、车辆、包裹）、门铃响铃以及设备连接/断开。

unifi_protect_list_devices

列出 Protect 传感器、灯具、响铃器、查看器和门锁。

unifi_protect_get_stream_url

返回摄像机的 RTSPS URL，以便在 VLC、ffmpeg 或媒体播放器中打开。

操作（安全）

工具

功能说明

UniFi Network

unifi_block_client

阻止设备接入网络，或解除已有的阻止。使用同一工具即可完全撤销。

unifi_reconnect_client

强制无线客户端重新连接（踢下线）。可用于将设备切换到另一个频段或接入点。

unifi_authorize_guest

在访客门户上为客户端授权一段时间，或撤销该访问权限。

unifi_set_client_name

在控制器中为客户端设置易记的名称和/或备注。

unifi_restart_device

重启接入点、交换机或网关本身。软重启会重启软件；硬重启会断电并重新上电。

unifi_locate_device

让 UniFi 设备闪烁 LED，方便你在物理上找到它，或停止闪烁。

unifi_power_cycle_port

对 PoE 交换机端口执行断电重启，从而重启接入该端口的设备。

unifi_set_wlan_enabled

打开或关闭 SSID，例如访客网络或 IoT 网络。

unifi_run_speedtest

在网关上开始测速，或读取正在运行的测速状态。

unifi_create_voucher

创建一个或多个访客热点券。

unifi_revoke_voucher

删除访客券，使其无法再被使用。

UniFi Protect

unifi_protect_set_doorbell_message

在 UniFi 门铃的屏幕上显示自定义消息，或将其重置为默认消息。可逆。

unifi_protect_set_light

强制打开或关闭 UniFi Protect 泛光灯，或将控制权交还给移动侦测。

配置（完整）

工具

功能说明

UniFi Network

unifi_set_port_forward_enabled

打开或关闭现有的端口转发规则。

unifi_set_firewall_rule_enabled

打开或关闭现有的防火墙规则。

unifi_update_wlan

修改 SSID 上的设置（名称、密码、频段、访客策略等）。仅更改提供的键。

unifi_update_network

修改 LAN/VLAN/WAN 定义上的设置。仅更改提供的键。

unifi_upgrade_device

在 UniFi 设备上开始固件升级。设备在升级完成后会重启。

UniFi Protect

unifi_protect_set_recording_mode

设置摄像机的录制时机：始终、仅在检测到事件时或从不。这会影响你的安防录像。

unifi_protect_update_device

修改 Protect 设备（摄像机、传感器、灯具、响铃器、查看器）上的任意设置。仅更改提供的键。

每个列表工具都接受 detail: "summary" | "full"；站点级工具接受 site 以覆盖已配置的站点。

配置参考

变量

默认值

描述

UNIFI_HOST

(必填)

控制台的主机名或 IP 地址。假定使用 https://。

UNIFI_API_KEY

—

官方集成 API 的 API 密钥。

UNIFI_USERNAME / UNIFI_PASSWORD

—

用于内部 API 的本地 UniFi OS 账户。

UNIFI_MFA_TOKEN

—

一次性 2FA 验证码，仅当确实需要使用账户时填写。

UNIFI_SITE

default

网络站点名称。

UNIFI_PERMISSION_MODE

read-only

read-only、safe 或 full。

UNIFI_ALLOW_WRITE

false

映射到 safe 的布尔值替代项。

UNIFI_ALLOW_FULL_CONTROL

false

映射到 full 的布尔值替代项。

UNIFI_ENABLE_NETWORK

true

启用网络工具。

UNIFI_ENABLE_PROTECT

true

启用 Protect 工具。

UNIFI_VERIFY_TLS

false

验证控制台的证书。控制台在本地地址上使用自签名证书。

UNIFI_TIMEOUT_MS

20000

每次请求的超时时间。

至少需要一组凭据；如果未配置任何凭据，服务器将退出并显示说明。

安全说明

  • 凭据存储在你的 MCP 客户端配置中。在 Claude Desktop 中，插件会将 API 密钥和密码存储在系统钥匙串中，因为它们被标记为 sensitive。

  • 默认情况下关闭 TLS 验证，因为 UniFi 控制台在其局域网地址上使用自签名证书。连接仍然是加密的，但未经过身份验证——请将服务器放在你信任的网络上，或安装合适的证书并设置 UNIFI_VERIFY_TLS=true。

  • 助手从你的网络中读取的所有内容（客户端名称、备注、SSID、事件消息）都是不可信输入。因此，除非有理由，否则应让服务器保持只读模式。

  • 除你的控制台和你所连接的 MCP 客户端外，不会向任何地方发送任何数据。

故障排除

先运行 unifi_status——它会报告哪些凭据通过了身份验证、哪些应用程序响应了，以及当前生效的权限模式。

症状

可能的原因

login: invalid username or password（登录：用户名或密码无效）

使用了 Ubiquiti SSO 账户，而不是本地账户，或者该账户启用了 2FA。

requires two-factor authentication（需要双因素身份验证）(HTTP 499)

请创建一个未启用 2FA 的本地账户。

Could not reach the UniFi console（无法访问 UniFi 控制台）

UNIFI_HOST 填写错误，或机器无法访问控制台。先尝试运行 curl -k https://<host>/。

self-signed certificate（自签名证书）错误

请保持 UNIFI_VERIFY_TLS=false。

Protect 工具显示 unreachable（无法访问）

控制台上未安装 Protect，或 API 密钥没有 Protect 访问权限。设置 UNIFI_ENABLE_PROTECT=false 以隐藏这些工具。

工具列表中缺少某个工具

需要更高的权限级别，或相应的应用程序已被禁用。

only available through the internal UniFi Network API（仅可通过内部 UniFi Network API 使用）

该数据不在集成 API 中——请添加 UNIFI_USERNAME/UNIFI_PASSWORD。

开发

npm install
npm run build          # compile TypeScript to dist/
npm run typecheck      # types only
npm run inspect        # MCP Inspector against the local build
npm run bundle         # build unifi-mcp-<version>.mcpb

添加工具：在 src/tools/ 中使用 defineTool() 定义，声明其 tier 和 feature，并从 src/tools/index.ts 导出。scripts/sync-manifest-tools.mjs 会保持 manifest.json 同步（它在 npm run bundle 时运行）。

发布

npm version minor          # bumps package.json and creates the v-tag
git push --follow-tags

发布工作流会构建 bundle，并将 unifi-mcp-<version>.mcpb 和 SHA256SUMS.txt 附加到 GitHub release 中。

兼容性

针对 UniFi OS 4.x、UniFi Network 9.x 和 UniFi Protect 6.x 开发，测试环境为 UDR，包括入墙式和独立式接入点、一个 LTE 摄像头和一个门铃。其他 UniFi 控制台使用相同的 API 接口。对于特定控制台或固件未实现的端点，会返回明确的错误，而不是静默失败。

许可证

MIT — 参见 LICENSE。

与 Ubiquiti Inc. 无关联、未经其认可、亦未获得其支持。UniFi 是 Ubiquiti Inc. 的商标。

This server cannot be installed

A
license - permissive license
Not graded
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
1Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • UniFi MCP Server

    vandreus
    A
    license
    D
    quality
    D
    maintenance
    Enables comprehensive management of UniFi network infrastructure through the UniFi Cloud API, including device control, client management, camera settings, and access door control through natural language.
    39
    52
    Apache 2.0

  • UniFi MCP Server

    MidwestMountaineer
    A
    license
    B
    quality
    D
    maintenance
    Enables AI assistants to manage and monitor UniFi Network Controllers through natural language. Provides 25 read-only tools for discovering devices and clients, viewing security configurations, analyzing network statistics, and exporting configuration data.
    41
    MIT

  • UniFi MCP Server

    gbassaragh
    F
    license
    Not graded
    quality
    D
    maintenance
    Provides AI assistants with access to UniFi Network and Protect infrastructure for managing devices, monitoring clients, analyzing network health, viewing camera snapshots, and getting optimization recommendations across multiple UniFi controllers.
    2

  • UniFi MCP Server

    enuno
    A
    license
    C
    quality
    A
    maintenance
    Enables AI agents to manage UniFi network infrastructure via the Model Context Protocol, supporting device management, network configuration, security, and QoS through local or cloud APIs.
    43
    52
    235
    Apache 2.0

View all related MCP servers

Related MCP Connectors

  • emisar

    Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.

  • GitHub

    Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.

  • SentinelX MCP

    Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mbgroen/unifi-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server