使用说明

UniFi网络MCP

UniFi网络应用程序的只读数据检索器（UniFi操作系统和经典版）。为LLM客户端提供TypeScript库函数、CLI和MCP服务器。此仓库包含自托管MCP所需的TypeScript源代码、规范和每个代理的配置片段。

特性

具有独立身份验证、TLS、超时和速率限制的多个控制器目标。
身份验证流程：UniFi操作系统通过 POST /api/auth/login 经典via POST /api/login.
路由：UniFi操作系统下 /proxy/network/api/...，经典下 /api/....
网络集成API（API密钥）支持：
- GET /integration/v1/info → get_sysinfo
- GET /integration/v1/sites → list_sites
- GET /integration/v1/sites/{siteId}/devices → get_devices
- GET /integration/v1/sites/{siteId}/clients → get_clients
只读。没有突变。

范围说明： 当连接从UniFi网络集成UI生成的API密钥时，只有上面列出的集成API终结点才能保证在UniFi Dream Machine/UniFi OS控制器上工作。端点，例如 stat/health, stat/event，以及 stat/report 需要用户名/密码身份验证，并且对Integration API密钥不可用。

先决条件

Node.js 20+
npm 10+
UniFi网络控制器（UDM/UDR/UXG或UniFi操作系统网关）
从生成的集成API密钥 UniFi网络→ 设置→ 系统→ 集成
git 以及POSIX shell（macOS/Linux）

配置和构建

克隆并安装：

git clone https://github.com/ryanbehan/unifi-network-mcp.git
cd unifi-network-mcp/servers/unifi-network-mcp
npm install

出口 UNIFI_TARGETS （单个或多个控制器）。例子：
```
export UNIFI_TARGETS='[
  {
    "id": "home",
    "base_url": "https://<unifi_host>",
    "controller_type": "unifi_os",
    "default_site": "default",
    "auth": { "apiKey": "UNIFI_API_KEY", "headerName": "X-API-KEY" },
    "verify_ssl": false,
    "timeout_ms": 20000,
    "rate_limit_per_sec": 5
  }
]'
```
关键字段：
- ID：此UniFi目标的友好名称（例如。 home, lab).使用此 id 作为 targetId 当您有多个控制器时，在MCP工具调用中。
- base_url：UniFi控制器的基本URL（例如。 https://<unifi_host>).这与您用于访问UniFi网络UI的URL相同。
- auth.apiKey: UNIFI_API_KEY 从...获得 UniFi网络→ 设置→ 系统→ 集成 对于网络应用。
- 默认_站点：工具调用未指定时使用的默认站点 site.经常 Default；如果控制器使用不同的站点名称，请检查Integration API 站点网络应用程序中的端点。
支持多个目标：
```
export UNIFI_TARGETS='[
  { "id": "home", "base_url": "https://<unifi_host_home>", "controller_type": "unifi_os", "default_site": "Default", "auth": { "apiKey": "UNIFI_API_KEY_HOME", "headerName": "X-API-KEY" }, "verify_ssl": false, "timeout_ms": 20000, "rate_limit_per_sec": 5 },
  { "id": "lab",  "base_url": "https://<unifi_host_lab>",  "controller_type": "unifi_os", "default_site": "Default", "auth": { "apiKey": "UNIFI_API_KEY_LAB",  "headerName": "X-API-KEY" }, "verify_ssl": false, "timeout_ms": 20000, "rate_limit_per_sec": 5 }
]'
```
- 当一目标已配置，MCP工具可以省略 targetId 并将自动使用该单个目标。
- 当多个目标已配置，通过 targetId （例如。 home 或 lab)在MCP工具参数中，这样服务器就知道要使用哪个控制器。
示例工具调用（多目标）：
- 列出网站 home （默认站点）：
  - 概念参数： { "targetId": "home" }
- 从以下位置获取设备 lab / Default 网站：
  - 概念参数： { "targetId": "lab", "site": "Default" }
- 例如，使用Codex CLI：
```
codex exec "call get_devices with targetId lab and site Default" --skip-git-repo-check
```
构建一次（发射 dist/ 以下每个工具共享的工件）：
```
npm run build
```

从发布版快速安装

curl -L https://github.com/ryanbehan/unifi-network-mcp/releases/download/v0.1.0/unifi-network-mcp-v0.1.0.tar.gz | tar -xz -C ~/.local/share/
cd ~/.local/share/unifi-network-mcp
cp .env.example .env
# Edit .env with your UNIFI_TARGETS

公共运行时命令

所有快速启动都使用相同的启动脚本，该脚本验证 UNIFI_TARGETS，根据需要构建，并在STDIO上启动MCP：

cd /path/to/unifi-network-mcp
./run-mcp.sh

在IDE/CLI与MCP通信时，让此进程运行。

特定工具快速启动

风浪/瀑布（npx）

在Windsurf： 插件→ 模型上下文协议→ 添加MCP服务器→ 地方指挥部.
命令： npx
论据： -y unifi-network-mcp

添加环境变量 UNIFI_TARGETS 如果未全局导出，请在对话框中（粘贴JSON字符串）：

[{"id":"home","base_url":"https://<unifi_host>","controller_type":"unifi_os","default_site":"Default","auth":{"apiKey":"UNIFI_API_KEY","headerName":"X-API-KEY"},"verify_ssl":false,"timeout_ms":20000,"rate_limit_per_sec":5}]

保存；Windsurf将自动从npm获取MCP，并在下面公开工具 我的MCP服务器.

光标（npx）

创建/更新 .cursor/mcp.config.json 在您的repo中：

{
  "servers": [
    {
      "name": "unifi-network",
      "command": "npx",
      "args": ["-y", "unifi-network-mcp"],
      "env": {
        "UNIFI_TARGETS": "[{\"id\":\"home\",\"base_url\":\"https://<unifi_host>\",\"controller_type\":\"unifi_os\",\"default_site\":\"Default\",\"auth\":{\"apiKey\":\"UNIFI_API_KEY\",\"headerName\":\"X-API-KEY\"},\"verify_ssl\":false,\"timeout_ms\":20000,\"rate_limit_per_sec\":5}]"
      }
    }
  ]
}

重新加载光标（Cmd+Shift+P→ “重新加载窗口”）。光标将 npx 必要时使用MCP。

Codex（基于npx的安装）

将此块添加到 ~/.codex/config.toml:

[mcp_servers.unifi-network-mcp]
    command = "npx"
    args = ["-y", "unifi-network-mcp"]
    [mcp_servers.unifi-network-mcp.env]
        UNIFI_TARGETS = '[{"id":"home","base_url":"https://<unifi_host>","controller_type":"unifi_os","default_site":"Default","auth":{"apiKey":"UNIFI_API_KEY","headerName":"X-API-KEY"},"verify_ssl":false,"timeout_ms":20000,"rate_limit_per_sec":5}]'

提示： 替换 <API_KEY> 以及任何具有您自己值的控制器元数据。Codex将在首次启动时自动下载+缓存MCP。

从任何repo运行 codex exec list_sites --skip-git-repo-check 以确认连接。

Gemini CLI（npx）

安装谷歌 gemini CLI（早期访问）并启用MCP支持。

创建 ~/.gemini/mcp.yaml:

servers:
  - name: unifi-network
    command: npx
    args:
      - -y
      - unifi-network-mcp
    env:
      UNIFI_TARGETS: "[{\"id\":\"home\",\"base_url\":\"https://<unifi_host>\",\"controller_type\":\"unifi_os\",\"default_site\":\"Default\",\"auth\":{\"apiKey\":\"UNIFI_API_KEY\",\"headerName\":\"X-API-KEY\"},\"verify_ssl\":false,\"timeout_ms\":20000,\"rate_limit_per_sec\":5}]"

跑 gemini mcp servers list 确认一下，然后 gemini chat --use-mcp unifi-network.

亚马逊Q CLI（npx）

安装Amazon Q开发人员预览CLI。

编辑 ~/.aws/amazonq/mcp.json:

{
  "servers": [
    {
      "name": "unifi-network",
      "command": "npx",
      "args": ["-y", "unifi-network-mcp"],
      "env": {
        "UNIFI_TARGETS": "[{\"id\":\"home\",\"base_url\":\"https://<unifi_host>\",\"controller_type\":\"unifi_os\",\"default_site\":\"Default\",\"auth\":{\"apiKey\":\"UNIFI_API_KEY\",\"headerName\":\"X-API-KEY\"},\"verify_ssl\":false,\"timeout_ms\":20000,\"rate_limit_per_sec\":5}]"
      }
    }
  ]
}

使用以下命令启动Q CLI amazon-q chat --mcp unifi-network.

开放代码

创建或编辑 ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "unifi-network-mcp": {
      "type": "local",
      "command": ["npx", "-y", "unifi-network-mcp"],
      "enabled": true,
      "environment": {
        "UNIFI_TARGETS": "[{\"id\":\"home\",\"base_url\":\"https://<unifi_host>\",\"controller_type\":\"unifi_os\",\"default_site\":\"Default\",\"auth\":{\"apiKey\":\"UNIFI_API_KEY\",\"headerName\":\"X-API-KEY\"},\"verify_ssl\":false,\"timeout_ms\":20000,\"rate_limit_per_sec\":5}]"
      }
    }
  }
}

重新启动Opencode或重新加载配置；这 unifi-network-mcp 服务器将在聊天中可用。

克劳德代码（人类VS代码扩展）

打开VS代码 设置（JSON） （命令选项板→ “首选项：打开设置（JSON）”）。

在下面添加或合并以下内容 claude.mcpServers 按键：

"claude.mcpServers": {
  "unifi-network-mcp": {
    "command": "npx",
    "args": ["-y", "unifi-network-mcp"],
    "env": {
      "UNIFI_TARGETS": "[{\"id\":\"home\",\"base_url\":\"https://<unifi_host>\",\"controller_type\":\"unifi_os\",\"default_site\":\"Default\",\"auth\":{\"apiKey\":\"UNIFI_API_KEY\",\"headerName\":\"X-API-KEY\"},\"verify_ssl\":false,\"timeout_ms\":20000,\"rate_limit_per_sec\":5}]"
    }
  }
}

重新加载VS代码。Claude Code将通过npm启动MCP；证实 @mcp unifi-network-mcp list_sites 克劳德聊天。

对于 克劳德终端/全局配置 （在VS代码之外），将服务器添加到 ~/.claude/settings.json:

{
  "mcpServers": {
    "unifi-network-mcp": {
      "command": "npx",
      "args": ["-y", "unifi-network-mcp"],
      "env": {
        "UNIFI_TARGETS": "[{\"id\":\"home\",\"base_url\":\"https://<unifi_host>\",\"controller_type\":\"unifi_os\",\"default_site\":\"Default\",\"auth\":{\"apiKey\":\"UNIFI_API_KEY\",\"headerName\":\"X-API-KEY\"},\"verify_ssl\":false,\"timeout_ms\":20000,\"rate_limit_per_sec\":5}]"
      }
    }
  }
}

保存后，重新启动克劳德终端或桌面；这 unifi-network-mcp 服务器也将在那里可用。

GitHub Copilot聊天（npx）

您可以通过添加GitHub记录的相同格式的本地服务器配置，使用此MCP扩展GitHub Copilot Chat：

每个存储库（推荐）：创建一个 .vscode/mcp.json 将文件放在repo的根目录中。
全球VS代码：向您的用户添加相同的JSON settings.json 在Copilot的MCP配置下（有关确切的密钥名称，请参阅GitHub文档）。

示例 mcp.json 此服务器的内容：

{
  "servers": {
    "unifi-network-mcp": {
      "command": "npx",
      "args": ["-y", "unifi-network-mcp"],
      "env": {
        "UNIFI_TARGETS": "[{\"id\":\"home\",\"base_url\":\"https://<unifi_host>\",\"controller_type\":\"unifi_os\",\"default_site\":\"Default\",\"auth\":{\"apiKey\":\"UNIFI_API_KEY\",\"headerName\":\"X-API-KEY\"},\"verify_ssl\":false,\"timeout_ms\":20000,\"rate_limit_per_sec\":5}]"
      }
    }
  }
}

验证

npm run test:env 电话 list_sites 针对每个配置的目标，在TLS/auth错误时快速失败。

单个工具烟雾测试：

codex exec get_sysinfo --skip-git-repo-check

分发选项

共享预构建的MCP，而无需每个消费者都运行 npm install:

GitHub发布工件
- 跑 npm run build 填充 dist/.
- 包裹 dist/, node_modules/, run-mcp.sh，以及 package.json 进入 unifi-network-mcp-<version>.tar.gz.
- 在GitHub发布，以便其他人可以下载、设置 UNIFI_TARGETS，然后运行 ./run-mcp.sh 无需编译TypeScript。
GitHub页面/原始静态托管
- 将tarball提交给 releases/ 通过GitHub Pages进行简单的分支和服务 curl | tar 安装。
自制水龙头（可选）
- 创建一个公式，下载发布tarball，验证校验和，并将包装器脚本放入 /usr/local/bin.
容器图片 （如果需要运行时隔离）
- 使用以下命令构建最小的Node 20映像 dist/ 复制，通过暴露STDIO docker run --entrypoint ./run-mcp.sh ....

每种方法都使项目可以自由分发（只有预构建的JS+shell脚本），同时让下游用户跳过TypeScript工具链。

仓库

GitHub: https://github.com/ryanbehan/unifi-network-mcp
最新版本: https://github.com/ryanbehan/unifi-network-mcp/releases/latest

使用说明

UniFi网络MCP

特性

先决条件

配置和构建

从发布版快速安装

公共运行时命令

特定工具快速启动

风浪/瀑布（npx）

光标（npx）

Codex（基于npx的安装）

Gemini CLI（npx）

亚马逊Q CLI（npx）

开放代码

克劳德代码（人类VS代码扩展）

GitHub Copilot聊天（npx）

验证

分发选项

仓库

相关 MCP

Prometheus数据检索服务器

TypeScript重构工具

生物数据查询服务

开放数据协议服务器

Steam 评测检索 MCP 服务

文本差异生成服务