使用说明

UniFi MCP服务器

通过AI控制你的UniFi网络。由OpenAPI规范支持的2-tool设计——与 UniFi云API 或 本地梦想机器.

它做什么

查询设备、客户端、网络统计信息
管理WiFi、VLAN、防火墙规则
创建网络配置
监控网络健康状况

快速设置（5分钟）

1.获取UniFi API密钥

首选 account.ui.com
登录→ 设置→ API密钥
创建新密钥→ 复制它

2.使用npx运行（无需安装）

UNIFI_API_TYPE=cloud-ea UNIFI_API_KEY=your-key-here npx @bakhshb/unifi-mcp

或者创建一个 .env 文件：

UNIFI_API_TYPE=cloud-ea
UNIFI_API_KEY=your-key-here

然后运行：

npx @bakhshb/unifi-mcp

3.连接到Claude/OpenClaw

开爪 (~/.openclaw/openclaw.json):

{
  "mcp": {
    "servers": {
      "unifi": {
        "command": "npx",
        "args": ["@bakhshb/unifi-mcp"],
        "env": {
          "UNIFI_API_TYPE": "cloud-ea",
          "UNIFI_API_KEY": "your-key-here"
        }
      }
    }
  }
}

克劳德桌面 (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "unifi": {
      "command": "npx",
      "args": ["@bakhshb/unifi-mcp"],
      "env": {
        "UNIFI_API_TYPE": "cloud-ea",
        "UNIFI_API_KEY": "your-key-here"
      }
    }
  }
}

本地Dream机器设置

你的 本地UniFi控制器 （Dream Machine等）也支持API密钥，就像云API一样。在控制器设置中生成API密钥：

转到您的UniFi控制器→ 设置→ API密钥
为本地访问创建新密钥
使用与cloud相同的env变量，但 UNIFI_API_TYPE=local

UNIFI_API_TYPE=local
UNIFI_API_KEY=your-local-api-key
UNIFI_LOCAL_HOST=192.168.1.1
UNIFI_LOCAL_VERIFY_SSL=false

或者在openclaw.json中：

{
  "mcp": {
    "servers": {
      "unifi": {
        "command": "npx",
        "args": ["@bakhshb/unifi-mcp"],
        "env": {
          "UNIFI_API_TYPE": "local",
          "UNIFI_API_KEY": "your-local-api-key",
          "UNIFI_LOCAL_HOST": "192.168.1.1",
          "UNIFI_LOCAL_VERIFY_SSL": "false"
        }
      }
    }
  }
}

环境变量

变量	必填	默认	描述
`UNIFI_URL`	是	-	您的UniFi控制器URL（例如。， `https://192.168.1.1` 或 `https://api.ui.com` 对于云）
`UNIFI_API_KEY`	是*	-	您的API密钥(*如果不使用用户名/密码，则需要）
`UNIFI_USERNAME`	是的*	-	UniFi用户名(*如果不使用API密钥，则需要）
`UNIFI_PASSWORD`	是的*	-	UniFi密码（如果不使用API密钥，则需要*）
`UNIFI_SITE_ID`	没有	`default`	您的UniFi站点标识符
`UNIFI_TIMEOUT`	没有	`30000`	请求超时（毫秒）

注：设置其中之一 UNIFI_API_KEY 或(UNIFI_USERNAME + UNIFI_PASSWORD).

注：对于本地模式，您还可以使用会话Cookie(UNIFI_SESSION_COOKIE + UNIFI_CSRF_TOKEN)而不是API密钥，但API密钥更简单。

解释API模式

UniFi MCP支持三种连接模式，通过设置 UNIFI_API_TYPE:

模式	何时使用	需要授权	速率限制
`local`	局域网上的Dream Machine/UDM Pro SE	API密钥	无
`cloud-v1`	通过Ubiquiti云进行远程管理（稳定）	API密钥	10000 req/min
`cloud-ea`	通过Ubiquiti云进行远程管理（早期访问）	API密钥	100 req/min

local --直接连接到本地网络上的UniFi控制器。完全访问，无外部流量，无速率限制。需要 UNIFI_LOCAL_HOST.

cloud-v1 -托管于的稳定云API api.ui.com向后兼容，长期支持。更高的速率限制，但仅设置核心功能。

cloud-ea -早期访问云API api.ui.com较新的功能在登陆v1之前，但速率限制较低，可能仍在发展。站点管理器API和一些较新的端点首先住在这里。

选择哪一个？

家庭实验室/本地网络 → local （您的UDM Pro SE）
远程管理，生产稳定 → cloud-v1
远程管理，需要最新功能 → cloud-ea

命令

`unifi-api`

执行任何UniFi Integration API调用。示例：

unifi-api 和 path="/v2/sites" → 列出所有网站
unifi-api 和 path="/v1/sites/{siteId}/devices" 和 pathParams={siteId:"default"} → 获取设备
unifi-api 和 path="/v1/sites/{siteId}/clients" 和 pathParams={siteId:"default"} → 获得客户

`unifi-api-schema`

发现可用的集成API操作：

无参数→ 列出所有标签/操作
tag="sites" → 现场操作
path="/v1/sites/{siteId}/devices" → 该路径的详细信息

`unifi-legacy-client-stats`

从获取每个客户端的带宽统计数据 传统控制器API (/api/s/{site}/stat/sta).此端点与Integration API分离，并返回每个客户端的实时tx/rx字节和速率。

为什么要使用单独的工具？ UniFi OpenAPI规范（beezly/UniFi-apis）未涵盖传统控制器API。它存在于同一控制器上，但使用不同的路径(/proxy/network/api/s/)并返回集成API中不可用的带宽数据（tx_bytes，rx_bytes、tx_rate、rx_rate）。

参数	类型	默认值	说明
`site`	字符串	`"default"`	站点名称或ID

示例响应：

{
  "success": true,
  "message": "Legacy client stats: 2 active clients on site 'default'",
  "data": {
    "count": 2,
    "site": "default",
    "clients": [
      {
        "hostname": "iPhone",
        "ip": "192.168.1.100",
        "mac": "aa:bb:cc:dd:ee:ff",
        "network": "Home",
        "vlan": 1,
        "is_wired": false,
        "tx_bytes": 1234567890,
        "tx_bytes_formatted": "1.15 GB",
        "rx_bytes": 987654321,
        "rx_bytes_formatted": "941.8 MB",
        "tx_rate_bps": 1500,
        "tx_rate_formatted": "1.5 Kbps",
        "rx_rate_bps": 800,
        "rx_rate_formatted": "800 bps",
        "uptime": 3600,
        "uptime_formatted": "1h 0m",
        "signal": -50,
        "essid": "MyWiFi",
        "ap_name": "UDM-Pro"
      },
      {
        "hostname": "laptop",
        "ip": "192.168.1.50",
        "mac": "11:22:33:44:55:66",
        "network": "Home",
        "vlan": 1,
        "is_wired": true,
        "tx_bytes": 50000000,
        "tx_bytes_formatted": "47.7 MB",
        "rx_bytes": 100000000,
        "rx_bytes_formatted": "95.4 MB",
        "tx_rate_bps": 0,
        "tx_rate_formatted": "0 B/s",
        "rx_rate_bps": 0,
        "rx_rate_formatted": "0 B/s",
        "uptime": 7200,
        "uptime_formatted": "2h 0m",
        "ap_name": "Switch"
      }
    ]
  }
}

故障排除

“需要API密钥” → Set UNIFI_API_KEY 在您的环境中

“连接被拒绝” → Check UNIFI_LOCAL_HOST 对于本地模式

SSL错误 → Set UNIFI_LOCAL_VERIFY_SSL=false 本地

建筑

代币节省： 传统的UniFi MCP服务器每次会话的成本约为45000-60000个令牌。对于集成API，2工具+1遗留方法的成本约为500–1500个令牌，对于遗留统计工具-a，成本约为200个令牌 减少约97%.

方法	工具	代币成本	覆盖范围
enuno/unifi mcp服务器（显式）	148	~45000–60000	已修复
西尔柯比/unifi mcp （多产品）	~82	~25000–35000	网络+保护+访问+驱动
此服务器（2-工具+1旧版）	3工具	~700–1,700	44+集成API操作+遗留统计数据

3工具 而不是148个显式工具→ ~97% 更少的上下文开销
用于集成API的2个通用工具（OpenAPI规范驱动，与API表面动态缩放）
1个用于带宽统计的传统工具（不在OpenAPI规范中，特定于控制器）
灵感源自 @dokploy/mcp (战术发射/dokploy mcp)--第一个演示2工具OpenAPI模式的MCP服务器，在大约500个令牌中涵盖463个Dokloy操作
OpenAPI规范来自 beezly/unifi原料药（其API研究渊源可追溯至西尔柯比/unifi mcp)

许可证

MIT许可证

使用说明

UniFi MCP服务器

它做什么

快速设置（5分钟）

1.获取UniFi API密钥

2.使用npx运行（无需安装）

3.连接到Claude/OpenClaw

本地Dream机器设置

环境变量

解释API模式

命令

unifi-api

unifi-api-schema

unifi-legacy-client-stats

故障排除

建筑

许可证

相关 MCP

串口AI控制工具

浏览器AI控制协议

浏览器自动化工具

网络控制协议服务器

桌面控制服务器

游戏AI控制模块

`unifi-api`

`unifi-api-schema`

`unifi-legacy-client-stats`