lancontrol

Name: lancontrol
Author: CloudCorpRecords

本地服务

github.com/CloudCorpRecords云与基础设施01 周前更新

代码仓库

关于 lancontrol

lancontrol 是用于读取 UniFi Network 控制器状态的命令行工具和 stdio MCP 服务，为网络运维人员提供精简的查询操作，涵盖客户端、设备、WLAN、站点健康、告警、事件、系统信息和身份。

主要功能

01读取已连接客户端和网络设备
02查看 WLAN 配置与站点健康状态
03获取告警和近期事件
04读取控制器系统信息与身份
05同一二进制文件支持命令行和 MCP 服务

适用场景

01查看已连接客户端和接入点
02检查站点健康状态与活动告警
03查询近期控制器事件
04获取 UniFi 控制器身份和系统详情

MCP 相关

通过一个 `unifi` 工具及其操作参数提供八种控制器查询和本地帮助。stdio MCP 服务从环境变量读取 `UNIFI_URL` 和 `UNIFI_API_KEY`。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "cloudcorprecords-lancontrol": {
      "command": "npx",
      "args": [
        "-y",
        "@reneturcios/lancontrol"
      ]
    }
  }
}

启动命令npx -y @reneturcios/lancontrol

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@reneturcios/lancontrol0.1.0stdio

ocighcr.io/cloudcorprecords/lancontrol:0.1.0stdio

工具

收录的工具列表 · 更新于 1 周前

参数	类型	必填	说明
limit	integer	否	要返回的事件最大数量，必须为正整数；仅 events 操作支持此参数。
action	enum	是	要运行的操作：clients、devices、wlans、health、alarms、events、sysinfo、me 或 help。clients \| devices \| wlans \| health \| alarms \| events \| sysinfo \| me \| help

详细介绍

lancontrol

lancontrol 通过单个操作路由工具读取 UniFi Network 控制器状态：已连接的客户端、网络设备、WLAN 配置、站点运行状况、活动警报、近期事件、控制器系统信息，以及经过身份验证的身份。一个二进制文件同时提供命令行界面和 stdio MCP 服务。

这是一个带标签的核心子集。上游接口总共定义了 267 个操作；lancontrol 仅构建保留的 8 个便捷操作以及 help（共 9 个操作值）。特意按名称省略生成的操作系列：official_*（78 个操作）、unifi_*（175 个操作）以及 5 个混合别名（list_clients、list_devices、list_networks、list_wifi、get_system_info）。

配置

除 help 外，每个操作都必须设置这两个变量；缺少值时会在发出任何请求前报错：

变量	必需	用途
`UNIFI_URL`	是	控制器基础 URL，例如 `https://unifi.local`。
`UNIFI_API_KEY`	是	API 密钥，通过 `X-API-KEY` 标头发送。
`UNIFI_SITE`	否	UniFi 站点名称。默认为 `default`。

切勿将 API 密钥作为工具参数传递；它只会从环境中读取。

安装

npx @reneturcios/lancontrol help

或者运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/lancontrol

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。

CLI

lancontrol clients
lancontrol devices
lancontrol wlans
lancontrol health
lancontrol alarms
lancontrol events --limit 25
lancontrol sysinfo
lancontrol me
lancontrol help

lancontrol --version

操作命令会输出上游 JSON 负载。help 会输出本地操作文档，无需配置或网络连接。退出代码：成功时为 0，调用失败时为 1（包括缺少配置或上游 API 错误），用法错误时为 2。

MCP 服务

一个二进制文件提供两种功能。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/lancontrol mcp

MCP 客户端配置：

{
  "mcpServers": {
    "lancontrol": {
      "command": "npx",
      "args": ["-y", "@reneturcios/lancontrol", "mcp"],
      "env": {
        "UNIFI_URL": "https://unifi.local",
        "UNIFI_API_KEY": "...",
        "UNIFI_SITE": "default"
      }
    }
  }
}

工具

提供一个工具：

工具	输入	返回内容
`unifi`	`action`（必需，为 9 个子集值之一）、`limit`（可选整数，仅适用于 `events`）	所选操作的上游负载，或 `help` 的本地文档。

操作	说明
`clients`	已连接的无线和有线客户端。
`devices`	网络设备：AP、交换机、网关。
`wlans`	WiFi 网络配置。
`health`	站点运行状况摘要。
`alarms`	活动警报和提醒。
`events`	近期控制器事件。
`sysinfo`	控制器系统信息。
`me`	经过身份验证的 UniFi 身份。
`help`	内置操作文档。

上游映射（文档化重建）

公开规范列出了操作名称，但未在便捷操作表中公布每个操作对应的确切控制器路径。因此，每个操作都会通过 X-API-KEY 标头，向 UNIFI_URL 下一个合理且有文档记载的 UniFi 内部端点发送 GET 请求：

操作	端点
`clients`	`GET /proxy/network/api/s/{site}/stat/sta`
`devices`	`GET /proxy/network/api/s/{site}/stat/device`
`wlans`	`GET /proxy/network/api/s/{site}/rest/wlanconf`
`health`	`GET /proxy/network/api/s/{site}/stat/health`
`alarms`	`GET /proxy/network/api/s/{site}/stat/alarm`
`events`	`GET /proxy/network/api/s/{site}/stat/event`（提供 limit 时附加 `?_limit={limit}`）
`sysinfo`	`GET /proxy/network/api/s/{site}/stat/sysinfo`
`me`	`GET /proxy/network/api/self`
`help`	不发送请求 — 在本地处理

HTTP 失败时会显示状态码，以及可用时的上游消息（meta.msg、message 或 error）。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx