Skip to main content
Glama
deenesjakoruzh
pete-builds

mcp-unifi

by pete-builds
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

mcp-unifi

CI Release License: MIT Python MCP Coverage

一个用于自托管 UniFi 网关管理的 MCP 服务器。包含十五个工具，涵盖设备、网络/VLAN、WiFi SSID（完整 CRUD）、防火墙规则（完整 CRUD）、交换机端口配置文件、已连接客户端，以及一个 create_iot_network 一次性工具，该工具可在单次调用中配置隔离的 IoT 子网（VLAN、SSID 和防火墙拦截），并在部分失败时自动回滚。

基于 FastMCP 和 Streamable HTTP 传输构建。通过本地 API 密钥与 UCG-Fiber、UDM Pro 或任何其他 UniFi OS 网关通信。无需 Site Manager / 云账户。

每个工具都返回 JSON。错误以结构化的 {"error": "...", "stub_mode": bool} 对象形式返回，因此 MCP 循环永远不会因为网关故障而崩溃。

为什么选择它

目前大多数 UniFi 自动化意味着点击控制器 UI、编写脆弱的一次性脚本或引入沉重的社区 SDK。mcp-unifi 为任何支持 MCP 的客户端（Claude Code、Claude Desktop、自定义代理）提供了一个小巧、专注且类型良好的操作界面，用于你每周实际执行的操作：启动 IoT VLAN、添加防火墙规则、审计 SSID、列出已采用的设备。

复合工具 create_iot_network 将 15 步的 UI 工作流程简化为单次工具调用。

Related MCP server: UniFi MCP

快速入门

拉取已发布的镜像并运行：

docker run --rm \
  -p 3714:3714 \
  -e STUB_MODE=true \
  ghcr.io/pete-builds/mcp-unifi:0.2.0

服务器默认在 存根模式 (stub mode) 下启动，该模式返回真实的模拟数据，无需 UniFi 硬件。将其注册到 Claude Code：

claude mcp add unifi --transport http --scope user --url http://localhost:3714/mcp

然后让 Claude Code "列出我的 UniFi 设备"，你应该会看到两个存根设备返回。

要与真实网关通信，请传入凭据并关闭存根模式：

docker run --rm \
  -p 3714:3714 \
  -e STUB_MODE=false \
  -e UNIFI_HOST=192.168.1.1 \
  -e UNIFI_API_KEY=<your-local-api-key> \
  ghcr.io/pete-builds/mcp-unifi:0.2.0

在网关的 设置 → 控制平面 → 集成 (Settings → Control Plane → Integrations) 下生成 API 密钥。

工具参考

工具

签名

功能

list_devices

()

列出已采用的网关、AP 和交换机，包含状态、运行时间和各射频信息。

list_networks

()

列出所有已配置的网络/VLAN（子网、DHCP 范围、VLAN ID）。

create_vlan

(name, vlan_id, subnet, dhcp_start?, dhcp_stop?, purpose?)

创建一个新的 VLAN 标记网络。

update_vlan

(network_id, updates)

修补现有 VLAN 上的字段。

delete_vlan

(network_id)

删除 VLAN。

list_wlans

()

列出所有 WiFi SSID。

create_wlan

(name, passphrase, network_id, security?, wpa_mode?, is_guest?, hide_ssid?, wlan_band?)

创建绑定到特定 VLAN 的新 SSID。

update_wlan

(wlan_id, updates)

修补现有 SSID 上的字段（名称、密码、hide_ssid 等）。

delete_wlan

(wlan_id)

删除 WiFi SSID。

list_firewall_rules

()

列出所有防火墙规则。

create_firewall_rule

(name, ruleset, action, rule_index?, protocol?, src_address?, dst_address?, src_networkconf_id?, dst_networkconf_id?, enabled?)

创建防火墙规则。

delete_firewall_rule

(rule_id)

删除防火墙规则。

list_port_profiles

()

列出交换机端口配置文件（PoE 模式、原生 VLAN、转发）。

list_clients

()

列出当前连接的无线和有线客户端（MAC、主机名、IP、信号/满意度、AP 或交换机端口、运行时间）。

create_iot_network

(name, vlan_id, passphrase, main_lan_subnet?, subnet?, isolate?, hide_ssid?)

一次性：VLAN + SSID + 隔离规则，失败时回滚。

每个工具都返回一个 JSON 字符串。错误以结构化的 {"error": "...", "stub_mode": bool} 对象返回，以便 Claude 可以渲染失败信息而不会导致 MCP 循环崩溃。

存根模式 vs 真实模式

模式

何时使用

行为

存根 (STUB_MODE=true, 默认)

开发、演示、在硬件到达前连接 Claude 流程

内存状态机，预置一个网关、一个 AP、一个网络、一个 SSID、一个防火墙规则、两个端口配置文件。创建/更新/删除在容器生命周期内持久化。重启后重置。

真实 (STUB_MODE=false)

使用 UCG-Fiber/UDM/其他 UniFi OS 网关的生产环境

使用本地 API 密钥通过 HTTPS 与网关通信。需要 UNIFI_HOST 和 UNIFI_API_KEY。

切换模式是配置更改，而非代码更改。相同的十一个工具，相同的响应形状。

配置

所有配置均从环境变量（以及存在时的 .env 文件）读取。配置在启动时由 Pydantic 验证；无效值会快速失败并显示有用的消息。

变量

类型

默认值

必需

说明

STUB_MODE

bool

true

否

为 false 时，需要真实模式凭据。

UNIFI_HOST

string

""

仅在真实模式

网关 IP 或主机名（无协议头）。

UNIFI_PORT

int

443

否

网关的 HTTPS 端口。

UNIFI_SITE

string

default

否

控制器站点标识符。

UNIFI_API_KEY

string

""

仅在真实模式

来自“设置 → 控制平面 → 集成”的本地 API 密钥。

UNIFI_VERIFY_SSL

bool

false

否

如果你在网关上安装了真实证书，请设为 true。

IOT_SUBNET_TEMPLATE

string

10.0.{vlan_id}.0/24

否

必须包含字面量 {vlan_id} 占位符。

IOT_DHCP_START_OFFSET

int (2-254)

100

否

IoT /24 内的第一个 DHCP 租约偏移量。

IOT_DHCP_STOP_OFFSET

int (2-254)

200

否

IoT /24 内的最后一个 DHCP 租约偏移量。

MCP_HOST

string

0.0.0.0

否

绑定地址。

MCP_PORT

int

3714

否

监听端口。

LOG_LEVEL

enum

INFO

否

DEBUG, INFO, WARNING, ERROR, CRITICAL 之一。

LOG_FORMAT

enum

json

否

生产环境用 json，本地开发用 text。

完整示例位于 .env.example。

MCP 客户端设置

Claude Code

claude mcp add unifi --transport http --scope user --url http://<host>:3714/mcp

Claude Desktop

将以下内容添加到你的 claude_desktop_config.json 中：

{
  "mcpServers": {
    "unifi": {
      "transport": "streamable-http",
      "url": "http://<host>:3714/mcp"
    }
  }
}

通用配置

Streamable HTTP 位于 http://<host>:3714/mcp。任何支持 Streamable HTTP 传输（规范 2025-03-26+）的 MCP 客户端均可连接。

架构

+---------------------+         Streamable HTTP         +---------------------+
|  MCP Client         |  -------------------------->    |  mcp-unifi          |
|  (Claude Code, etc) |  <--------------------------    |  (FastMCP server)   |
+---------------------+                                 +----------+----------+
                                                                   |
                                                                   |  HTTPS + X-API-Key
                                                                   v
                                                        +----------+----------+
                                                        |  UniFi OS Gateway   |
                                                        |  /proxy/network/... |
                                                        +---------------------+

该服务器是一个 轻量级异步代理：它将 MCP 工具调用转换为 UniFi 控制器 REST 调用，格式化响应并返回 JSON。它不存储状态，不调用任何云服务，也不验证传入的 MCP 连接（请在受信任的局域网内运行）。

安全说明

  • UNIFI_API_KEY 仅存在于容器的环境变量中。它永远不会被记录，永远不会在 MCP 响应中回显，也不会被此服务器写入磁盘。

  • WLAN 密码在每个工具响应输出时都会被清除（[REDACTED]），即使在存根模式下也是如此。

  • 容器以 UID 1000 运行，无 shell，无主目录，具有 只读根文件系统 (/tmp 为 tmpfs) 和 no-new-privileges。

  • 基础镜像按摘要固定。Python 依赖项使用 pip --require-hashes 从哈希锁定的 requirements.lock 安装。

  • 已发布的镜像为多架构 (amd64/arm64)，具有构建来源证明，并通过 docker/build-push-action 提供 SBOM。

  • MCP 服务器本身 未经过身份验证。请将其放置在受信任的局域网边界、带有身份验证的反向代理或 Tailscale ACL 之后。

有关漏洞报告，请参阅 SECURITY.md。

开发

需要 Python 3.13+ 和 Docker。

# Clone + install dev deps
git clone https://github.com/pete-builds/mcp-unifi.git
cd mcp-unifi
python -m venv .venv && source .venv/bin/activate
pip install --require-hashes -r requirements-dev.lock
pip install -e . --no-deps

# Run the test suite (101 tests, ~95% coverage)
pytest

# Lint and format
ruff check src tests
ruff format src tests

# Type check (mypy strict)
mypy src/mcp_unifi

# Run the server locally in stub mode
python -m mcp_unifi.server

# Or build the image yourself instead of pulling from GHCR
cp docker-compose.example.yml docker-compose.yml
docker compose up --build

测试

======================= 101 passed in 1.5s =======================

Name                          Stmts  Miss  Branch  BrPart  Cover
-----------------------------------------------------------------
src/mcp_unifi/__init__.py         2     0       0       0   100%
src/mcp_unifi/clients/__init__    3     0       0       0   100%
src/mcp_unifi/clients/stubs.py   70     1       6       0    99%
src/mcp_unifi/clients/unifi.py   82     0      12       0   100%
src/mcp_unifi/config.py          38     1       8       0    98%
src/mcp_unifi/healthcheck.py     18     1       0       0    94%
src/mcp_unifi/logging_setup.py   33     1      12       2    93%
src/mcp_unifi/models.py           6     0       0       0   100%
src/mcp_unifi/server.py         232    15      70       5    92%
-----------------------------------------------------------------
TOTAL                           484    19     108       7    95%

CI 门禁要求 最低 80% 的覆盖率、ruff lint、ruff format、mypy strict，以及对任何 HIGH 或 CRITICAL 发现都会失败的 Trivy fs+image 扫描。

更新依赖

requirements.lock 和 requirements-dev.lock 文件是哈希锁定的。编辑 requirements.in（或 requirements-dev.in），然后重新生成：

uv pip compile requirements.in --output-file requirements.lock --generate-hashes --python-version 3.13
uv pip compile requirements-dev.in --output-file requirements-dev.lock --generate-hashes --python-version 3.13

Dependabot 每周会为 requirements.in 级别的更新和 Docker 基础镜像摘要打开 PR。

致谢

UniFi 控制器端点路径参考了 sirkirby/unifi-mcp 项目。该仓库被用作 API 面的研究材料；未复制任何代码。此处的实现是一个独立的 FastMCP + httpx 构建，遵循经过验证的 Forge 模式。

许可证

MIT。

贡献

欢迎提交问题和拉取请求。在打开 PR 之前：

  1. 确保 ruff check, ruff format --check 和 mypy src/mcp_unifi 清洁。

  2. 添加或更新测试，保持覆盖率在 80% 或以上。

  3. 在本地运行 pytest 并确认套件通过。

  4. 在 [Unreleased] 标题下更新 CHANGELOG.md。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityActive
ResponsivenessSlow

Resources

Related MCP Connectors

Related MCP Servers

  • unifi-mcp

    kjmagnan1s
    A
    license
    Not graded
    quality
    D
    maintenance
    A safety-first MCP server for managing UniFi networks, exposing 17 tools for telemetry, diagnostics, and guarded mutations with dry-run previews and confirm requirements.
    14
    MIT

  • go-unifi-mcp

    claytono
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server for UniFi Network Controller enabling AI assistants to manage UniFi infrastructure via natural language. It supports firewall rules, IPv6, and uses lazy/eager tool modes to minimize context usage.
    6
    Mozilla Public 2.0