Unifi MCP Openapi

UniFi MCP服务器


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

它做什么

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

快速设置（5分钟）

1.获取UniFi API密钥

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

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密钥：

1. 转到您的UniFi控制器→ 设置→ API密钥
2. 为本地访问创建新密钥
3. 使用与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_API_KEY 或(UNIFI_USERNAME + UNIFI_PASSWORD).

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

解释API模式

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

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）。

示例响应：

{
  "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%.

• 3工具 而不是148个显式工具→ ~97% 更少的上下文开销
• 用于集成API的2个通用工具（OpenAPI规范驱动，与API表面动态缩放）
• 1个用于带宽统计的传统工具（不在OpenAPI规范中，特定于控制器）

许可证


MIT许可证