go-unifi-mcp

go-unifi-mcp

一个用 Go 编写的 UniFi Network Controller 模型上下文协议（MCP）服务。

概览

go-unifi-mcp 为 UniFi Network Controller 提供 MCP 接口，让 AI 助手和其他 MCP 客户端能够与您的 UniFi 基础设施交互。

为什么要开发它

我找不到同时支持 v1 和 v2 防火墙规则及 IPv6 的 MCP 服务，所以我自己开发了一个。它封装了 go-unifi 库（我在使用 Terraform 提供程序时就信任这个库），并依托其生成的 API 接口。该服务根据控制器自身的 API 定义生成，因此随着 UniFi 的演进，更容易及时更新工具覆盖范围。

UniFi 控制器版本

本项目针对 go-unifi 固定使用的同一 UniFi Controller 版本生成工具。go-unifi 更新支持的控制器版本后，我们会重新生成字段定义和工具元数据，使其保持一致。我们支持相同的控制器版本范围；请参阅其控制器支持范围。

安装

二进制文件（GitHub Releases）

从Releases 页面下载预构建的二进制文件。macOS 和 Linux（amd64/arm64）均有对应版本。

# macOS (Apple Silicon)
curl -L https://github.com/claytono/go-unifi-mcp/releases/latest/download/go-unifi-mcp_darwin_arm64.tar.gz | tar xz
sudo mv go-unifi-mcp /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/claytono/go-unifi-mcp/releases/latest/download/go-unifi-mcp_darwin_amd64.tar.gz | tar xz
sudo mv go-unifi-mcp /usr/local/bin/

# Linux (amd64)
curl -L https://github.com/claytono/go-unifi-mcp/releases/latest/download/go-unifi-mcp_linux_amd64.tar.gz | tar xz
sudo mv go-unifi-mcp /usr/local/bin/

# Linux (arm64)
curl -L https://github.com/claytono/go-unifi-mcp/releases/latest/download/go-unifi-mcp_linux_arm64.tar.gz | tar xz
sudo mv go-unifi-mcp /usr/local/bin/

Homebrew

可从 claytono/homebrew-tap tap 获取：

brew install claytono/tap/go-unifi-mcp

Nix

# Run without installing
nix run github:claytono/go-unifi-mcp

# Install to your profile
nix profile install github:claytono/go-unifi-mcp

Docker

多架构镜像（amd64/arm64）发布在 GitHub Container Registry。

# Latest (pinned to most recent release, rebuilt on base image updates)
docker pull ghcr.io/claytono/go-unifi-mcp:latest

# Edge (built from main on every merge, unstable)
docker pull ghcr.io/claytono/go-unifi-mcp:edge

Go 安装

go install github.com/claytono/go-unifi-mcp/cmd/go-unifi-mcp@latest

配置

UniFi 凭据

该服务需要访问 UniFi Network Controller。支持两种身份验证方式：

1. API 密钥（推荐）：在 UniFi 控制器的 Settings > Control Plane > Integrations 下创建 API 密钥。设置 UNIFI_HOST 和 UNIFI_API_KEY。

2. 用户名/密码：使用本地管理员账户。设置 UNIFI_HOST、UNIFI_USERNAME 和 UNIFI_PASSWORD。

Claude Desktop

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

使用二进制文件：

{
  "mcpServers": {
    "unifi": {
      "command": "/usr/local/bin/go-unifi-mcp",
      "env": {
        "UNIFI_HOST": "https://your-controller:443",
        "UNIFI_API_KEY": "your-api-key"
      }
    }
  }
}

使用 Docker：

{
  "mcpServers": {
    "unifi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "UNIFI_HOST",
        "-e",
        "UNIFI_API_KEY",
        "ghcr.io/claytono/go-unifi-mcp:latest"
      ],
      "env": {
        "UNIFI_HOST": "https://your-controller:443",
        "UNIFI_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

claude mcp add unifi -- go-unifi-mcp

然后，在运行 claude 前，于 shell 中设置所需的环境变量。

环境变量

变量	必需	默认值	说明
UNIFI_HOST	是	—	UniFi 控制器 URL
UNIFI_API_KEY	*	—	API 密钥（推荐的身份验证方式）
UNIFI_USERNAME	*	—	用于密码身份验证的用户名
UNIFI_PASSWORD	*	—	用于密码身份验证的密码
UNIFI_SITE	否	default	UniFi 站点名称
UNIFI_VERIFY_SSL	否	true	是否验证 SSL 证书
UNIFI_LOG_LEVEL	否	error	go-unifi 客户端日志级别
UNIFI_TOOL_MODE	否	lazy	工具注册模式

* 必须设置 UNIFI_API_KEY，或同时设置 UNIFI_USERNAME 和 UNIFI_PASSWORD。

日志级别

UNIFI_LOG_LEVEL 变量用于控制底层 go-unifi 客户端库的日志记录。默认值为 error，因为客户端默认会向 stderr 输出 INFO 消息，可能会干扰 mcp-cli 等需要解析 stdout/stderr 上 JSON 的工具。

级别	说明
disabled	不记录日志
trace	最详细，包含传输细节
debug	调试消息
info	信息性消息
warn	仅警告
error	仅错误（默认）

工具模式

该服务支持两种工具注册模式，遵循 unifi-network-mcp 建立的模式：

模式	工具	上下文大小	描述
lazy	3	~200 tokens	仅元工具（默认，推荐用于大模型）
eager	252	~55K tokens	直接注册所有工具

Lazy 模式（默认）仅注册 3 个元工具，可访问 252 项 UniFi 操作（由控制器 API 生成）：

• tool_index - 按类别或资源搜索/筛选工具目录
• execute - 按名称和参数执行任意工具
• batch - 并行执行多个工具

这样可以大幅减少上下文窗口用量，同时保留完整功能。大模型会先查询索引以查找相关工具，然后通过分发器执行这些工具。

Eager 模式会直接注册全部 252 个工具，可能适用于非大模型客户端或调试，但会占用大量上下文。

更新语义： 更新通过控制器 API 执行读取-修改-写入流程。我们会获取当前资源、合并你提供的字段，然后提交完整对象。这样可以避免清除未指定的字段，但该操作并非原子操作，而且并发更新可能发生竞争（最后写入者生效），因为 UniFi API 不会公开 etag 或修订 ID。实际中这不太可能成为问题，但仍需注意。

ID 解析

UniFi API 的响应包含不透明的 ID 引用（例如 network_id、 usergroup_id、networkconf_id）。默认情况下，服务会查找被引用的资源，将这些 ID 解析为人类可读的名称，并注入同级 _name 字段：

{
  "src_networkconf_id": "609fbf24e3ae433962e000de",
  "src_networkconf_name": "IOT"
}

解析会使用每次请求的缓存，因此，列出 100 条引用网络的防火墙规则时，只会额外调用一次 ListNetwork API。根据引用的不同资源类型数量，通常会增加 10–40 ms 的开销。

如需对特定调用禁用解析，请在工具参数中传入 "resolve": false。

查询参数

所有列表操作都支持可选的后处理参数，用于筛选和投影结果。

filter — 按字段值匹配项目。支持三种运算符：

// Exact match
{"filter": {"type": "usw"}}

// Substring match (case-insensitive)
{"filter": {"name": {"contains": "office"}}}

// Regular expression (RE2 syntax: https://github.com/google/re2/wiki/Syntax)
{"filter": {"name": {"regex": "^ap-.*"}}}

// Multiple conditions (ANDed together)
{"filter": {"type": "uap", "name": {"contains": "echo"}}}

search — 在所有字符串字段值中进行不区分大小写的全文搜索：

{ "search": "living room" }

fields — 将响应投影为仅包含指定键：

{ "fields": ["name", "ip", "mac"] }

参数可以组合使用。执行顺序为 filter → search → fields，因此可以按不会包含在输出中的字段进行筛选：

{
  "filter": { "type": "uap" },
  "search": "echo",
  "fields": ["name", "ip"]
}

开发

先决条件

• 启用 flakes 的 Nix
• direnv（可选，但推荐）

开发

# Clone the repository
git clone https://github.com/claytono/go-unifi-mcp.git
cd go-unifi-mcp

# Enter the development environment
nix develop
# Or with direnv:
direnv allow

# Install pre-commit hooks
pre-commit install

# Run linters
task lint

# Run tests
task test

# Run tests with coverage
task coverage

可用任务

task lint        # Run linters via pre-commit
task test        # Run tests
task coverage    # Run tests with coverage checks
task build       # Build the binary
task generate    # Run go generate

使用 mcp-cli 测试

开发环境包含用于交互式测试 MCP 服务的 mcp-cli。

1. 创建 .envrc.local 并填写 UniFi 凭据（不会纳入 git 跟踪）：

   export UNIFI_HOST="https://your-controller:443"
   export UNIFI_API_KEY="your-api-key"
   # Or use username/password:
   # export UNIFI_USERNAME="admin"
   # export UNIFI_PASSWORD="password"
   

2. 构建二进制文件：

   task build
   

3. 使用 mcp-cli 测试：

   .mcp_servers.json 配置提供两个服务条目：

   • go-unifi-mcp - eager 模式（252 个工具）
   • go-unifi-mcp-lazy - lazy 模式（3 个元工具）

   Eager 模式（直接访问工具）：

   # List tools (shows all 252)
   mcp-cli info go-unifi-mcp
   
   # Call a tool directly
   mcp-cli call go-unifi-mcp list_device '{}'
   mcp-cli call go-unifi-mcp list_network '{"site": "default"}'
   

   Lazy 模式（元工具）：

   # List tools (shows only 3 meta-tools)
   mcp-cli info go-unifi-mcp-lazy
   
   # Query the tool index
   mcp-cli call go-unifi-mcp-lazy tool_index '{}'
   mcp-cli call go-unifi-mcp-lazy tool_index '{"category": "list"}'
   mcp-cli call go-unifi-mcp-lazy tool_index '{"resource": "network"}'
   
   # Execute a tool via the dispatcher
   mcp-cli call go-unifi-mcp-lazy execute '{"tool": "list_device", "arguments": {}}'
   
   # Batch execute multiple tools
   mcp-cli call go-unifi-mcp-lazy batch '{"calls": [{"tool": "list_network", "arguments": {}}, {"tool": "list_device", "arguments": {}}]}'
   

致谢

本项目基于以下项目构建：

• go-unifi - UniFi Network Controller 的 Go 客户端库
• unifi-network-mcp - 为本项目提供灵感的 UniFi Python MCP 服务
• mcp-go - Model Context Protocol 的 Go SDK

许可证

MPL-2.0